pdfschema

Pull just the columns you need out of a PDF, so your LLM prompt carries data instead of a document.

pip install pdfschema

import pdfschema

rows = pdfschema.extract_rows(
    "statement.pdf",
    schema=["Date", "Particulars", "Debit"],
)

[
  {"Date": "01-04-2025", "Particulars": "PAYMENT MADE VIA UPI TO VPA MERCHANT7X2K@EXAMPLEPAY AGAINST REF 100000000001", "Debit": "390.00"}
]

_{Every example here uses fictional transaction data. The measurements below are real, taken from a 125-page statement that is not published.}

The problem this solves

Feeding a whole PDF to a model is the expensive way to answer a narrow question. A 125-page bank statement is ~44,000 tokens of prompt for every single call — and most of it is page furniture, letterhead, disclaimers and columns the question never touches. At scale that is the bill.

pdfschema lets you name the columns you actually need and get structured rows back. You extract once, then filter, aggregate or sample in Python before anything reaches the model.

Measured on a real 125-page statement

All six columns, typed schema:

Narrow the columns and it compounds: three columns as CSV is 21,565 tokens (−51%), two columns 4,687 (−89%).

Don't put JSON in a prompt. An array of objects repeats every key on every row, which on this document costs more than the raw text it replaced. Keep to_json() for the code that consumes the rows afterwards — that is what it's good at — and send one of the formats that names the fields once:

table = pdfschema.extract("statement.pdf", schema={
    "Date": "date", "Particulars": "string", "Debit": "number",
})[0]

prompt = f"Transactions:\n{table.to_toon(name='transactions')}\n\nWhich merchant took the most?"

transactions[970]{Date,Particulars,Debit}:
  2025-04-01,PAYMENT MADE VIA UPI TO VPA MERCHANT7X2K@EXAMPLEPAY AGAINST REF …,390
  2025-04-02,PAYMENT RECEIVED VIA UPI FROM VPA J.DOE-1@EXAMPLEBANK FROM …,null

_{(… marks text elided for width.)}

The real win is narrowing. Most of the saving comes from dropping columns and boilerplate the question never needed — and from filtering rows in Python, which no amount of prompt engineering over raw PDF text does reliably:

april = [r for r in rows if r["Date"].month == 4]   # with schema={"Date": "date"}

Why a schema, and not a grid detector

Most extractors look for the lines a page draws and infer columns from them. Bank statements, invoices and most generated business PDFs draw row bands but no vertical rules — so there is nothing to find, and those tools hand back one column with every row collapsed into a single string.

pdfschema starts from the header. Your labels are located on the page and their x positions become the column boundaries, so an unruled table reads exactly like a ruled one. The same labels identify the table's continuation on the next page, which is how a 125-page statement comes back as one table rather than 125 fragments.

Modes

Six independent switches that compose freely. Pick what you care about, leave the rest at their defaults.

table.strategy additionally reports how rows were found — "ruled" (the page drew them), "clustered" (inferred from word positions) or "mixed".

Extraction mode 1 — schema

Name the columns; get exactly those keys back, in your order and your spelling.

rows = pdfschema.extract_rows("statement.pdf", schema=["Date", "Balance"])

Matching is normalised subset: a table matches when its header supplies every label you asked for, compared case-insensitively with whitespace collapsed. Columns you didn't ask for are dropped. "transaction id", "Transaction ID" and "TRANSACTION ID" all find the same column.

If no table carries your columns you get SchemaNotFoundError — naming the unmatched labels and listing the headers that do exist — not an empty list your pipeline silently passes along.

Extraction mode 2 — discovery

Omit the schema and every table found comes back, keyed by the labels printed on the page:

for table in pdfschema.extract("statement.pdf"):
    print(table.header, table.n_rows, table.page_span)
# ['Date', 'Transaction ID', 'Particulars', 'Debit', 'Credit', 'Balance'] 970 1-125

Those labels are exactly what schema= accepts, so this is the first step when onboarding an unfamiliar document.

Value modes

rows = pdfschema.extract_rows("statement.pdf", schema={
    "Date": "date", "Debit": "number", "Particulars": "string",
})
rows[0]["Date"]   # datetime.date(2025, 4, 1)
rows[0]["Debit"]  # 390.0

number handles currency symbols, thousands separators, percentages and accounting negatives like (250.50). date tries a fixed list of formats.

Other modes

pdfschema.extract(path, schema, pages="1,3,5-7")   # page selection
pdfschema.extract(path, schema, merge=False)       # one table per page
pdfschema.extract(path, schema, join="newline")    # keep the PDF's line breaks
pdfschema.extract(path, schema, dayfirst=False)    # 01/04/2025 is 4 January
pdfschema.extract(path, schema, strict=True)       # raise instead of storing None

join decides how a cell wrapped over several lines is rebuilt. PDFs often chop text every N characters regardless of word boundaries, so a naive join gives you either @EXAMPLEPAYAGAINST or VP A MERCHANT; "smart" (the default) works the wrap style out per column and rebuilds the original string.

Output modes and types

Every extraction returns a list[Table]. The output mode is whichever method you then call — nothing about the extraction changes, only the shape you hand on.

to_dataframe() needs pip install pdfschema[pandas]; the rest are always available. The two TSONs are unrelated formats that share a name — one delimiter-based, one indentation-based — and pdfschema implements both rather than picking for you.

Picking a combination:

One thing worth knowing: every prompt format must quote a string that would otherwise read as a number, so an untyped Debit column emits "390.00" where schema={"Debit": "number"} emits 390. Typing the numeric columns makes the prompt smaller and less ambiguous.

These formats are newer than CSV and how reliably a given model reads one varies by model — benchmark against yours before switching a pipeline over.

Command line

$ pdfschema discover statement.pdf
[1] pages 1-125  rows 970  (ruled)
    schema: ["Date", "Transaction ID", "Particulars", "Debit", "Credit", "Balance"]

$ pdfschema extract statement.pdf --schema "Date:date,Debit:number" -o rows.json
$ pdfschema extract statement.pdf --schema "Date,Balance" --pages 1-5 --format csv
$ pdfschema extract statement.pdf --schema "Date:date" --format toon --name transactions

--format takes json (default), csv, toon, tson, tson-columnar. Also --pages, --name, --join, --no-merge, --monthfirst, --strict, -o/--output, --indent. extract exits 2 if the schema is not found.

What you get

• Deterministic and auditable. No model in the loop, no temperature, no hallucinated cells. The same PDF gives the same rows every time — which is what you want in the layer feeding an LLM.
• Wrapped cells rejoined correctly, multi-page tables merged, multi-table pages handled.
• Errors you can branch on. SchemaNotFoundError carries .unmatched and .headers_found; everything deliberate derives from PdfSchemaError.

Typical uses

• RAG ingestion — turn statements, invoices and reports into rows worth embedding, instead of embedding page images or raw text dumps.
• Agent tools — back a get_transactions(start, end) tool with a real extraction rather than a whole-document prompt.
• Batch pipelines — thousands of documents a day, where a 50% prompt reduction is the difference in the invoice.
• Pre-flight validation — check a document has the columns you expect before spending a model call on it.
• Plain ETL — no LLM anywhere; PDF to CSV, database or DataFrame.

Requirements

Python 3.11+ and pdfplumber. Optional: pdfschema[pandas] for to_dataframe().

Documentation

Full documentation, limitations and examples: https://github.com/nullbite-coder/pdfschema

MIT licensed.