io.github.benbergner/benspdf

Create a test PDF, handy for trying the other tools without hunting for one. The pages are blank, so this is for exercising tools rather than for anything that needs real content. Args: output_path: Optional path to also write the PDF to. Omit to keep it as a temporary artifact. num_pages: Number of blank pages to create (default: 3) title: Optional title for the PDF metadata

Delete temporary artifacts from the workspace now. Only accepts artifact ids, never file paths, so this cannot delete the user's own files. Artifacts expire on their own, so this is only needed when the user explicitly asks to clean up. Args: refs: Artifact id, or list of artifact ids, to delete.

Save one or more results to a real location on disk. The only tool that writes to the user's filesystem, so call it once at the end, when they have said where the output should go. Never hand an artifact id back as if it were a finished file; artifacts expire. Args: refs: Artifact id, or list of artifact ids, to export. dest: Where to write. For a single artifact this may be a full file path. For several artifacts, or when `name` is given, this is a directory and is created if missing. name: Filename template used when writing into a directory. Placeholders: {n} 1-based index (e.g. "page_{n:03d}{ext}"), {ext} extension, {id} artifact id, {stem} id without extension. Defaults to "{n:03d}{ext}". overwrite: Replace existing files instead of failing. Defaults to False so nothing is destroyed by accident.

List recent temporary artifacts in the workspace, newest first. Useful when you have lost track of an artifact id from earlier in the conversation, so you can find it again instead of redoing the work. Args: limit: Maximum number of artifacts to return.

Check a PDF's encryption and what it permits: printing, copying, editing. Answers "is this locked, and what am I allowed to do with it?". `encrypted` and `needs_password` are separate answers and the difference matters: most encrypted files have no user password, so they open silently and only carry restrictions. `permissions` gives a boolean per action, `restrictions` lists what is denied, and an unencrypted file permits everything — a PDF has nowhere to keep restrictions but its encryption dictionary. Treat restrictions as what the file asks of viewers, not as enforcement: once a document is open nothing stops the bits being ignored, and a file that denies copying still yields its text to pdf_extract_text. Report them as the author's intent, never as an action being impossible. Worth reaching for when another tool reports a file as encrypted; this one still answers, since the encryption dictionary is readable when the pages are not. Args: ref: PDF file path, or a workspace artifact id.

Check whether a PDF has a text layer, looks scanned, or needs OCR. Answers "can I read this, or is it a picture of a document?". Worth running before extracting text from a file you have not seen. `verdict` is "text", "scanned", "mixed", or "no_text" — the last meaning nothing readable but nothing scan-like either, so blank, vector-only, or illustrated pages that OCR cannot help. `needs_ocr` follows from it, `summary` is a sentence worth quoting, and the per page evidence behind the verdict comes back alongside, including each page's `image_coverage` (the largest image's share of the page area). Samples up to 10 pages spread across the document, so a true `sampled` means the answer is an estimate for the pages in between. It does not return the text (use pdf_extract_text) and it does not run OCR. Args: ref: PDF file path, or a workspace artifact id.

Read the text of a PDF that has one, page by page. The cheap and exact way to read a document: milliseconds a page, and the characters are the ones the file holds. Prefer it to pdf_ocr, which is for pages carrying no text, and to pdf_render_pages, which costs an image a page. pdf_check_text says which path a file needs; page numbers come back with the text, so quote page 8 rather than "the document". A long document arrives in ranges: one call returns about 50,000 characters and names the pages it did not reach, so when `truncated`, do what the summary says. `output="txt"` writes the whole extraction to an artifact and returns the counts alone, which is the way to read a book. Text on a `text_suspect` page came back partly undecodable, because the fonts carry no character map: say so rather than quoting it, and look at the page with pdf_render_pages. Args: ref: PDF file path, or a workspace artifact id. pages: Which pages: "1-10", "3", "1,5,9-12" or "all". Defaults to all. output: "text", "txt" for the text as an artifact, or "both". layout: Keep the page's spacing, for forms and tables. Costs characters.

Read a PDF's document properties: title, author, dates, producer, keywords. Answers "who made this, when, and with what". It does not count pages (use pdf_page_count) and says nothing about whether the pages hold readable text (use pdf_check_text). A PDF can store these fields in two independent places, the legacy Info dictionary and an XMP packet, and the two often disagree. The normalized answer is at the top level, preferring XMP, with `sources` naming the store each value came from and `conflicts` listing every field where the two differ, both values included. Both stores also come back verbatim as `info` and `xmp`. When `has_conflicts` is true, say so rather than quoting one value as fact. Args: ref: PDF file path, or a workspace artifact id.

Read a scanned PDF with OCR, and optionally add a real text layer to it. The way to read a page with no text: a scan, or an export that lost its text. Prefer it to pdf_render_pages for reading; run pdf_check_text when unsure. Tesseract is a system install, and a missing binary or language errors with how to install it. OCR can be confidently wrong, so pages report `mean_confidence` and `low_confidence_words`: say when confidence is low rather than presenting text as certain, and look at a bad page with pdf_render_pages. Text pages are skipped unless `force`. A long document may stop early; when `truncated`, do exactly what the summary says, artifact and range included. Args: ref: PDF file path, or a workspace artifact id. pages: Which pages: "1-10", "3", "1,5,9-12" or "all". Defaults to all. lang: Tesseract language code, or several as "eng+deu". dpi: Resolution, 72 to 600. 200 suits printed text; higher is slower, not better. output: "text", "pdf" for a searchable copy as an artifact, or "both". force: OCR pages that already have text instead of skipping them.

Count the pages in a PDF. Answers "how many pages is this?". Reads only the document's page tree, so it stays cheap on large files. It does not read page text, page sizes, or document properties. Args: ref: PDF file path, or a workspace artifact id.

Measure a PDF's page sizes, orientation and rotation. Answers "what size is this, is it all the same, and why does one page come out sideways?". Reads page geometry only, so it stays cheap on long documents. `sizes` groups the pages by shape, most pages first, each carrying the page numbers it covers as a range like "1-16,18", so a 300 page document answers in one entry instead of 300 rows. Sizes are the page as a reader sees it: CropBox clipped to MediaBox with `/Rotate` applied, so a landscape box rotated 90 degrees reports as portrait. Pages within 3pt of a known paper are grouped and named together, since real A4 varies by a millimetre. Pass `pages` for per page rows carrying the raw boxes: "1-20", "3", "1,5,9-12" or "all", capped at 100 rows. It does not look at page content; for whether the pages hold readable text use pdf_check_text. Args: ref: PDF file path, or a workspace artifact id. pages: Optional page range for per page detail. Omit for groups only.

Render PDF pages to images, so a page can be looked at rather than read. Use it to see what a page looks like: checking a change landed (did a redaction remove content, did a split cut where intended), previewing, and pages where appearance is the content — handwriting, signatures, charts, checkbox state. For *reading* a scan prefer pdf_ocr, whose text layer is searchable and needs no vision model; render when OCR is unavailable or would mangle what matters. Every page is saved as a PNG artifact and its id returned. With `view`, the default, the first few images also come back to be looked at, since images are expensive in context. Limits are explicit: 20 pages per call, and resolution is reduced for a page that would be enormous — both reported, never silent. Args: ref: PDF file path, or a workspace artifact id. pages: Which pages: "1-20", "3", "1,5,9-12" or "all". Defaults to all, up to the per-call limit. dpi: Resolution, 36 to 600. 150 suits reading and previewing. view: Return the images to look at, not just artifact ids.