PDF Explore

PDF Explore — navigate a PDF too big to embed

The built-in Read(file_path=..., pages=[...]) attaches PDF pages as vision blocks — capped at ~20 pages/turn and dropped from context after one turn, so multi-section synthesis turns into re-reading the same pages over and over. And when the answer is "every page" (list all datasets / citations / figures mentioned anywhere), reading the whole document page-by-page is the expensive way to get it.

This skill parses the PDF once into persistent per-page text, and — for whole-document work — runs one cheap model call per page (or per batch) in parallel via Task subagents, so the page text lives in files and subagent contexts, never in yours. You load only what matters, or sweep every page without putting the pages in your own context at all.

Read(pages=...) and this skill are complementary: use Read(pages=...) for a one-off look at 1–4 pages you will quote in your very next reply; use this skill for persistent text, multi-section synthesis, whole-doc sweeps, and structured extraction.

Loading the kernel

The helpers live in kernel.py next to this file. It is not auto-injected — import it by path in a Bash python heredoc (zero import-time side effects, all heavy imports are lazy):

python3 - <<'PY'
import importlib.util
K = "/ABSOLUTE/PATH/TO/pdf-explore/kernel.py"   # this SKILL.md's directory + /kernel.py
spec = importlib.util.spec_from_file_location("pdf_kernel", K)
k = importlib.util.module_from_spec(spec)
spec.loader.exec_module(k)

for e in k.pdf_outline("paper.pdf"):
    print(f"p{e['page']:>3} {'  ' * (e['level'] - 1)}{e['heading']}")
PY

Every recipe below assumes k is loaded this way. Each python invocation is a fresh process — the in-memory page cache does not survive between them, but page renders are cached on disk and re-extracting the text layer is cheap, so re-parsing the same file in a later call is fast.

Invocation. The recipes below all open with python3 - <<'PY', which is right when the deps are importable from your python3. If they aren't — or you would rather not install anything — prefix with uv, which fetches them into a throwaway env:

uv run --with pypdfium2 --with pillow --with pdfplumber python - <<'PY'

(Drop --with pdfplumber unless you're calling pdf_tables.) Otherwise pip install pypdfium2 pillow — plus pdfplumber for tables — and use plain python3 -.

Backend note: the default backend is pypdfium2 — Google PDFium, permissive Apache-2.0/BSD-3-Clause. PyMuPDF is honored as a fallback if already installed, but it is AGPL-3.0; if you embed it in a network service, AGPL's source-sharing terms apply. pdf_tables is the one helper on a second backend (pdfplumber), because PDFium exposes no table API at all. path can be a workspace path or a ~/-expanded path.

Which helper — inline vs Task fan-out

"Inline" = you read the page text (or figure crop) yourself and produce the answer in the same turn. "Fan-out" = the two-phase protocol below.

The fan-out protocol (scan / map / extract / outline over many pages)

Three steps. The page text never enters your context — it goes to files that subagents read.

1. PREPARE — call the *_prepare helper. It parses the PDF, writes the guarded page text into batched work files, and returns a small JSON manifest: instruction, (query / schema where relevant), return_spec, and items = [{pages, text_file, image_paths}, ...]. Only this small manifest lands in your context.
2. FAN OUT — for each item, launch a Task subagent. Its prompt = the manifest's instruction (+ query / schema) + "Read text_file (and Read each non-null image_paths entry), then return ONLY the JSON the return_spec describes." Each subagent returns a short JSON array — one object per page it handled. Launch the subagents in parallel.
3. ASSEMBLE — concatenate every subagent's array into one flat list, save it to results.json, and call the matching *_assemble helper. It ranks / merges / de-duplicates and returns the final result.

Batch to keep the subagent count sane. batch_size=N packs N pages into one work file → one subagent scores/summarizes all N. For a 120-page doc, batch_size=15 means 8 subagents, not 120. Default is 1 (one page per subagent); raise it for anything over ~20 pages.

A subagent handling untrusted document text returns data (scores / summaries / fields), never actions — and the work files wrap page text in per-job nonce delimiters the document can't forge, so a page that says "ignore your instructions" is inert.

Worked example — relevance scan of a whole paper

# 1. PREPARE
python3 - <<'PY'
import importlib.util, json
K = "/ABSOLUTE/PATH/TO/pdf-explore/kernel.py"
spec = importlib.util.spec_from_file_location("pdf_kernel", K)
k = importlib.util.module_from_spec(spec); spec.loader.exec_module(k)
m = k.pdf_scan_prepare("paper.pdf", query="batch-effect correction methods",
                       batch_size=10)
print(json.dumps(m, ensure_ascii=False, indent=1))
PY

2. Read the manifest. For each item, launch a Task subagent, e.g.:

   {instruction} {query} — Read the page text at {text_file}. For each page in it, score relevance in [0,1] and write one sentence on what the page contains. Return ONLY a JSON array [{"page":N,"score":x,"summary":"…"}], nothing else.

   Collect the arrays, concatenate them, and Write the flat list to results.json.

# 3. ASSEMBLE
python3 - <<'PY'
import importlib.util
K = "/ABSOLUTE/PATH/TO/pdf-explore/kernel.py"
spec = importlib.util.spec_from_file_location("pdf_kernel", K)
k = importlib.util.module_from_spec(spec); spec.loader.exec_module(k)
r = k.pdf_scan_assemble("paper.pdf", "results.json", top_k=5)
for h in r["hits"]:
    print(f"p{h['page']}  {h['relevance']:.2f}  {h['summary'] or h['text'][:100]}")
print(f"[{r['n_scanned']} pages scanned]")
PY

pdf_scan_assemble re-attaches each hit's persistent text, so you can then read the top pages' text directly, or Read(file_path='paper.pdf', pages=[...]) the few winners as vision. Pass threshold=0.7 instead of top_k to keep every page above a score.

When only a handful of pages are in play, skip the fan-out — print their text and scan/extract inline:

python3 - <<'PY'
... load k ...
for p in k.pdf_pages("paper.pdf", pages=[4, 5, 6, 7], mode="text"):
    print(f"\n== p{p['page']} ==\n{p['text'][:2000]}")
PY

Then answer from that output — no subagents needed.

Recipe — pull the sections you need as persistent text (synthesis)

For "summarize the methods" / "compare section 3 and section 5" — anything drawing on several page ranges at once — pull all the pages in one call, write them to a file, then Read that file (persistent, unlike vision pages):

python3 - <<'PY'
... load k ...
import os
wanted = [5, 21, 22, 23, 24, 25, 62, 63, 64]   # from pdf_outline
with open("sections.txt", "w") as f:
    for p in k.pdf_pages("paper.pdf", pages=wanted, mode="text"):
        f.write(f"\n── page {p['page']} ──\n{p['text']}")
print(f"wrote {os.path.getsize('sections.txt'):,} bytes")
PY

Then Read(file_path="sections.txt") (with offset/limit if over ~100KB) and write the answer from that. ~800 tokens/page as text vs ~4,000/page as vision — and it stays in context. Don't print() a whole chapter directly; write it to a file and Read it. For a quick look at ≤5 pages, printing is fine.

Recipe — navigate by outline (try this first)

python3 - <<'PY'
... load k ...
for e in k.pdf_outline("report.pdf"):
    print(f"p{e['page']:>3} {'  ' * (e['level'] - 1)}{e['heading']}")
PY

Free and instant when the PDF has an embedded outline (most LaTeX-compiled papers do). If pdf_outline returns [] (no embedded outline), it prints a hint: rebuild the TOC with the fan-out protocol using pdf_outline_prepare(path) → subagents → pdf_outline_assemble(results, n_pages=…). pdf_outline_prepare auto-picks a single holistic subagent for text-layer docs ≤150pp, or per-page subagents for scanned/long docs; each subagent returns [{"page","heading"}] (single-call) or [{"page","section_headings":[...]}] (per-page), and pdf_outline_assemble infers levels and de-duplicates. For a semantic question the outline doesn't obviously answer ("where do they discuss limitations"), use the scan protocol.

Recipe — read a figure in detail

A full rendered page downsamples to ≤1568px on attach, so a dense figure ends up illegible no matter the DPI. There are two ways out, and which one works depends on how the figure was drawn.

First try pdf_images — the figure at its native resolution

If the figure is a raster (a photo, a screenshot, an exported PNG/JPEG plot — most non-LaTeX papers), it is embedded in the PDF as an image object and you can pull the original pixels straight out. That beats cropping a page render, because the page render already threw resolution away:

python3 - <<'PY'
... load k ...
for e in k.pdf_images("paper.pdf", pages=[5]):
    print(f"p{e['page']} idx{e['index']} {e['px_size']} {e['bbox']} -> {e['image_path']}")
PY

Then Read(file_path="<image_path>"). Results come back largest-first, so the real figures lead and decoration trails. A logo repeated on every page collapses to one entry whose pages lists them all; anything with a side under min_px (64) is dropped as decoration.

Concretely, on a typical paper the page-1 figure is embedded at 2372×1359, while the whole page rendered at 100 dpi is only 788×1075 — so a crop of that figure would be roughly 570×326. Same figure, ~4× the linear detail, for less work.

Fall back to render + crop for vector figures

pdf_images only sees raster objects. A TikZ / pgfplots / matplotlib-PDF figure is drawing operations, not an image — it will not appear, and pdf_images returning [] on a figure-rich LaTeX paper is the expected, correct answer, not a bug. For those, rasterize the page yourself and crop:

python3 - <<'PY'
... load k ...
# Render page 5 at dpi=200 (lands in .cache/, not attached), then crop.
p = k.pdf_pages("paper.pdf", mode="image", pages=[5], dpi=200)[0]
print("page render:", p["image_path"])
crop = k.pdf_crop(p["image_path"], (x0, y0, x1, y1))   # pixels in the dpi=200 render
print("crop:", crop)
PY

Then Read(file_path="<crop path>") — more legible and cheaper than the full page (~400 vision tokens vs ~1,600). First Read the full page render to locate the figure if you don't know its box; crop one panel at a time for multi-panel figures. Always crop from the .cache/ render, never from a previously attached (downsampled) view.

Fidelity note

pdf_images defaults to render=True, saving the image as pdfium composites it — alpha and masks applied, so what you Read is what the page shows. Pass render=False to write the original encoded bytes instead (lossless for JPEG/JPEG-2000, and much smaller), but pdfium's raw extraction ignores alpha masks, so a figure with transparency can come out visibly wrong. Prefer the default when you are going to read the figure; use render=False when you want the original asset.

Recipe — extract tables

pdf_tables parses tables deterministically — no model, no vision, no fan-out — and every table comes back tagged with the page it came from:

python3 - <<'PY'
... load k ...   # needs pdfplumber: uv run --with pdfplumber ...
for t in k.pdf_tables("paper.pdf"):
    print(f"p{t['page']} #{t['index']}  {t['n_rows']}×{t['n_cols']}  -> {t['csv_path']}")
    for row in t["rows"]:                      # preview only, capped
        print("   ", row)
PY

The full table is written to csv_path; only a preview_rows-capped preview comes back inline, so a 300-row table never lands in your context. When you actually need all of it, Read the CSV (or pandas.read_csv it) — same rule as the rest of the skill: bulk goes to a file, not into the conversation.

Detection defaults to ruled lines. For a whitespace-aligned table with no rules, pass table_settings={"vertical_strategy": "text", "horizontal_strategy": "text"}. Ruled-line detection also fires readily on boxed captions and framed paragraphs, which arrive as n×1 "tables" — the min_rows/min_cols floor (2×2) drops those; lower min_cols=1 if you genuinely want single-column boxes.

Prefer this over a schema fan-out for tables. A pdf_extract_prepare sweep with {rows:[{col1,col2}]} pays a model per page to re-derive structure that pdfplumber reads off the page geometry for free — and gets ruled tables wrong often enough to matter. Reach for the fan-out only when what you want isn't the table grid but a judgment about it.

Recipe — map every page

For docs with no useful section structure (transcripts, slide exports), summarize every page with the fan-out protocol and pdf_map_prepare / pdf_map_assemble. Each subagent returns [{"page","text"}]; pdf_map_assemble("doc.pdf", "results.json") returns {pages:[{page,text,n_chars,image_path}], n_pages} in page order. Nothing is filtered out, so no relevant page is missed. Then pick pages and Read them.

Recipe — structured extraction (exhaustive list of X)

Pull the same fields from every page, in parallel, with pdf_extract_prepare / pdf_extract_assemble. Pass a JSON-Schema object; each subagent returns [{"page","data":{…}}], then flatten + dedupe in your own context:

python3 - <<'PY'
... load k ...
import json
m = k.pdf_extract_prepare("paper.pdf", {
    "type": "object",
    "properties": {
        "figures": {"type": "array", "items": {"type": "object",
            "properties": {"label": {"type": "string"},
                           "caption": {"type": "string"}}}},
    },
    "required": ["figures"],
}, batch_size=10)
print(json.dumps(m, ensure_ascii=False, indent=1))
PY
# … fan out subagents (they get instruction + schema, Read text_file, return
#    [{"page","data":{...}}]) → concatenate to results.json …
python3 - <<'PY'
... load k ...
rows = k.pdf_extract_assemble("results.json")
figs = [(r["page"], f) for r in rows for f in (r["data"] or {}).get("figures", [])]
for pg, f in figs:
    print(pg, f.get("label"), "—", (f.get("caption") or "")[:80])
PY

Put the inclusion criterion in the schema field's description — e.g. "datasets on which results are actually reported on this page, not datasets merely cited". The per-page subagent applies it for you; leaving it out means re-reading pages later to apply it yourself.

Schemas that work well: {figures:[{label,caption}]}, {citations:[str]}, {section_headings:[str]}, {gene_symbols:[str]} (entity lists). Schemas that don't: anything needing judgment about "key" vs "all" ({key_claims:[str]} returns ~10/page, unusable) — per-page extraction is recall-complete but precision-noisy. And not table grids — use pdf_tables, which reads the structure off the page geometry for free instead of paying a model per page to guess at it.

The sweep already read every page. Don't follow it with Read(pages=...) loads to "check for missed items" — that re-spends the tokens the sweep saved. For ≲300 raw names, print the sorted unique names with their page lists and dedupe/normalize while writing the final answer; if you must re-check a few pages, collect them all up front into one pdf_pages(pages=[...]) call (cached, instant) and print their text.

When NOT to use this skill

• A one-off look at 1–4 pages you quote immediately: Read(file_path=..., pages=[...]) is fine — but only if you write your answer that same turn.
• Literal keyword search: grep the extracted text — [p for p in k.pdf_pages(path) if "Harmony" in p["text"]]. The scan protocol earns its cost on semantic queries only.

Mode (scanned PDFs)

All parse helpers default to mode="auto": try text extraction; if pages average < 80 extractable characters (scanned document, image-only slide export), re-parse with page rendering so the subagent can Read the page image. You don't need to set this. "text"/"image" force one or the other; image-mode work files carry image_paths for the subagent to Read.

Cost & budget

~800 input + ~100 output tokens/page in text mode. Run the fan-out subagents on a cheap (Haiku-class) model — heavier models cost 10–30× more and add nothing to recall-complete per-page pulls. Token usage isn't visible to the kernel (the calls run inside subagents), so pdf_scan_cost reports only n_calls/n_errors, not tokens. For a very large document, scan a subset via pages=range(1, n, 3), but stride sampling can miss a narrow relevant span — prefer pdf_outline → read the section when the document has structure.

Caching

pdf_pages caches on (abs_path, mtime, mode, dpi) within a single Python process. Derived assets persist on disk under ./.cache/pdf-explore/{sha8}-{mtime}/:

so a re-render, a re-extract, or a re-prepare after a crash is cheap. The dir is keyed on mtime, so editing the PDF invalidates every stale asset. These are scratch artifacts for the agent to Read, not a deliverable — nothing is written outside .cache/ unless you ask for it.