PDF Explore

PDF Explore — navigate a PDF too big to embed

A 50-page PDF via read_file is ~200K tokens in context, and pages loaded with read_file(pages=[...]) are 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 the datasets / citations / figures / benchmarks mentioned anywhere in this document), reading the whole thing page-by-page is the expensive way to get it. This skill parses the PDF once in the Python kernel and runs one cheap haiku call per page, in parallel, so you load only what matters — or sweep every page without ever putting the pages in your own context.

Which helper

Loading this skill auto-injects these into the Python kernel (from kernel.py); call directly, no import. Don't check for or install pypdfium2 first — host-managed installs seed it in the default python environment, and if it's genuinely missing the first call raises with an install recipe (on platform-managed hosts the default env rejects installs — if the recipe's manage_packages call errors, create a domain env with pypdfium2 and pillow and re-run there; pillow does the PNG encoding for mode="image" and is not pulled in by the pypdfium2 wheel). Go straight to the helper call.

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-licensed (commercial licenses available from Artifex): if you embed it in a network-accessible service, AGPL's source-sharing terms apply to that service.

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

For "summarize the methods" / "compare section 3 and section 5" / anything where the answer draws on several page ranges at once, do not read the ranges one read_file call at a time — each call's pages are dropped from context before you finish, and you will loop re-reading them. Pull all the pages you need in one python call, write them to a file, then read_file that:

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

Then read_file(file_path="sections.txt") — or with offset=/limit= if it's over 100KB — and write the answer from that. Don't print() the page text directly: any python output over ~16KB is spilled to disk and you'll be told to read_file it anyway, so printing a full chapter costs two tool calls where writing + reading costs the same two without the wasted preview. (For a quick look at ≤5 pages, printing is fine.)

~800 tokens/page of text vs ~4,000 tokens/page as vision — and you only pay it once. Find the page numbers from pdf_outline (below) or the paper's own table of contents first.

Recipe — navigate by outline (try this first)

for e in pdf_outline("report.pdf"):
    print(f"p{e['page']:>3} {'  ' * (e['level'] - 1)}{e['heading']}")
# → then read_file(file_path="report.pdf", pages=[the section you want])

Free and instant when the PDF has an embedded outline (most LaTeX-compiled papers do). Falls back to a single batched LLM call on text-layer ≤150pp docs ($0.001-0.003 total), or per-page LLM heading extraction on scanned/>150pp ($0.002/page). For a semantic question the outline doesn't obviously answer ("where do they discuss limitations"), fall through to pdf_scan.

Recipe — find the pages relevant to a query

r = pdf_scan("paper.pdf", query="batch-effect correction methods", 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, "
      f"{r['usage']['input_tokens']} in + {r['usage']['output_tokens']} out]")

(summary is populated only when strategy="fanout" — the default "auto" uses single-call comparative ranking on text-mode docs ≤150pp, which is ~3× cheaper and ranks better but doesn't generate summaries. Pass strategy="fanout" if you want them.)

Then load only those:

# Either: call read_file from the harness (attaches as vision)
#   read_file(file_path="paper.pdf", pages=[h["page"] for h in r["hits"]])
# Or: print the text right here
for h in r["hits"]:
    print(f"\n── page {h['page']} ──\n{h['text'][:2000]}")
# Or: render hit pages to cwd (PNGs auto-attach as vision next turn).
# Fine for layout/skimming — but a full page is too low-res to read
# small values off a figure; for that use the next recipe instead.
for p in pdf_pages("paper.pdf", mode="image",
                   pages=[h["page"] for h in r["hits"]], dpi=150):
    import shutil; shutil.copy(p["image_path"], f"./hit_p{p['page']}.png")

path can be a workspace path, a ~/-expanded path, or an artifact version_id (resolved via host.artifact_path).

Recipe — read a figure in detail

A full rendered page is too low-resolution to read small axis labels, legend text, or values off a dense multi-panel figure — the attach pipeline downsamples everything to ≤1568px, so the figure region ends up at a few hundred pixels no matter what DPI you render at. Render the page at high DPI, then crop the figure before attaching. The crop is both more legible and cheaper (a figure crop is ~400 vision tokens vs ~1,600 for the full page).

# 1. Find the figure's page (pdf_scan on the caption text, or pdf_extract
#    with {"figures": [...]}, or you already know it).
# 2. Render that page at dpi=200 — high enough to crop into. The render
#    lands in .cache/ so it is NOT auto-attached.
p = pdf_pages("paper.pdf", mode="image", pages=[5], dpi=200)[0]
# 3. Attach the full page once to locate the figure, OR go straight to a
#    crop if the caption/position tells you where it is:
host.view_image(p["image_path"], crop=(x0, y0, x1, y1))  # pixels in the dpi=200 render
# → writes the crop to cwd; it auto-attaches at full resolution next turn.

Crop to one panel at a time for multi-panel figures. Always crop from the .cache/ render, not from a previously attached (downsampled) view.

Recipe — map every page

For documents with no useful section structure (meeting transcripts, slide exports, multi-document compilations), get a 2-sentence summary of every page instead of a ranked subset:

m = pdf_map("transcript.pdf")
for p in m["pages"]:
    print(f"p{p['page']}: {p['text']}")

Then pick pages and read_file(pages=[...]). 100 pages → ~10K tokens in context (vs ~400K if you embedded the whole PDF as vision, or ~90K as extracted text). Nothing is filtered out, so there's no chance the relevant page was missed. Measured: ~100 output tokens/page.