PDF Processing

pypdf, pdfplumber, pymupdf, pdf2image, pypdfium2, pytesseract, reportlab, and pillow are pre-installed. Run Python files with python3 script.py. Use uv run --with <package> script.py only for a package that is not pre-installed.

Quick Start

python

from pypdf import PdfReader, PdfWriter

reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

text = "".join(page.extract_text() or "" for page in reader.pages)

Use this for fast inspection. Move to the tool-specific sections below when you need layout-aware extraction, OCR, forms, rendering, or creation.

When to Use Which Tool

Task	Tool	Details
Convert to Markdown	anydoc	`anydoc document.pdf -o out.md` — no OCR; scanned PDFs exit `1`
Create PDF from scratch	ReportLab	[blocked]
Read / merge / split / rotate / encrypt	pypdf	—
Extract text and tables	pdfplumber	[blocked]
Render pages to images	pypdfium2	[blocked]
Create/manipulate in JavaScript	pdf-lib	—
CLI merge/split/encrypt/optimize/repair	qpdf	[blocked]
CLI text extraction	pdftotext	[blocked]
CLI image extraction	pdfimages	[blocked]
CLI page rendering	pdftoppm	[blocked]
OCR scanned PDFs	pytesseract + pdf2image	Convert to images, then OCR
Fill PDF forms	pypdf or pdf-lib	form-filling.md [blocked]
Convert PDF to Word	pdf2docx (load docx skill)	See docx skill — Converting PDF to Word

Form filling: You MUST read form-filling.md [blocked] before attempting to fill any PDF form.

Design and Typography

Design defaults: See skills/design-foundations/SKILL.md for palette, fonts + PDF pairings, chart colors, and core principles (1 accent + neutrals, no decorative imagery, accessibility).

Typography: PDFs embed any TTF font — use distinctive, professional fonts, not system defaults. Download from Google Fonts at runtime, register with ReportLab, and it embeds automatically. See [blocked] (Custom Fonts section) and skills/design-foundations/SKILL.md (PDF Pairings table + Font Strategy by Format). Default to a clean sans-serif (Inter, DM Sans, Work Sans).

CJK text: Fonts like Inter and DM Sans only cover Latin glyphs. ReportLab has no automatic font fallback — unregistered scripts render as tofu. Register Noto Sans CJK for Chinese, Japanese, or Korean text. See [blocked] (CJK Font Support).

Currency & symbol glyphs: The same Latin-only fonts also lack many currency and symbol glyphs — e.g. ₹ (U+20B9), ₩, ₫, ₴, ﷼. ReportLab and matplotlib render these as tofu with no fallback (matplotlib warns Glyph ... missing from font(s)). Either register a font that includes the glyph (e.g. Noto Sans), or use an ASCII fallback consistently (e.g. Rs for INR) across both charts and PDF body text so they match.

PDF Metadata

Always set metadata when creating PDFs:

Author should default to "SingulaComp" unless the user asks for a different organization or author name
Title should be a descriptive name relevant to the document contents

Canvas API: c.setTitle(...), c.setAuthor("SingulaComp") right after creating the canvas. SimpleDocTemplate: pass title=..., author="SingulaComp" as constructor kwargs. pdf-lib (JS): doc.setTitle(...), doc.setAuthor("SingulaComp").

Source Citations

Every PDF that includes information from web sources MUST have:

Numbered superscript footnote markers in body text (using <super> tags, never Unicode superscripts)
A numbered source list at the bottom of each page with clickable hyperlinked URLs

Each footnote entry must include the actual URL wrapped in an <a href> tag — never omit the URL or substitute a plain-text source name. See [blocked] (Source Citations) for the implementation pattern.

Hyperlinks

All URLs in generated PDFs must be clickable. In ReportLab Paragraph objects, use <a href="..." color="blue"> markup. On the canvas, use canvas.linkURL(url, rect). See [blocked] (Hyperlinks).

Subscripts and Superscripts

Never use Unicode subscript/superscript characters in ReportLab PDFs. Built-in fonts lack these glyphs, rendering them as black boxes. Use <sub> and <super> XML tags in Paragraph objects. For canvas text, manually adjust font size and y-offset. See [blocked] (Subscripts and Superscripts).

Tips

Text extraction: pdftotext is the fastest option for plain text. Use pdfplumber when you need tables or coordinate data — don't use pypdf.extract_text() on large documents, it's slow.

Image extraction: pdfimages extracts embedded images directly and is much faster than rendering whole pages. Only render with pypdfium2 or pdftoppm when you need a visual snapshot of the page layout.

Large PDFs: Process pages individually or in chunks rather than loading the entire document. Use qpdf --split-pages to break up very large files before processing.

Encrypted PDFs: Use pypdf to detect and decrypt (reader.is_encrypted / reader.decrypt(pw)). If you don't have the password, try qpdf --password=X --decrypt. Run qpdf --show-encryption to inspect what protection is applied.

Corrupted PDFs: Run qpdf --check to diagnose structural problems, then qpdf --replace-input to attempt repair.

Verifying generated PDFs: Rendering pages to images (pypdfium2/pdftoppm) only helps if your model can view images. If it can't, verify via text extraction instead — dump page.extract_text() with pypdf and check content, ordering, and that nothing overflowed — and confirm metadata (title, author) is set.

Text extraction fails: If pdfplumber or pdftotext return empty/garbled text, the PDF is likely scanned images. Fall back to OCR (see below).

OCR for Scanned PDFs