Starter kit for a PDF tool

What you get

Left to you, because no check can do it: Open one compressed file of your own in your usual viewer and printer before relying on the default quality: 150 dpi suits screens and office printers, not print shops.

Toolbox

Installed along with them: pytest 9.1.1.

For your agent

Licenses of the assets

License terms as the sources state them, read on the dates shown. The kit's CREDITS.md starts with these rows and the brief tells the agent to add one for every file it brings in. This is a record, not legal advice.

The plan your agent follows

The agent works one step at a time and does not start a step until the previous one meets its "Done when" lines. The full instructions, with code, are in AGENTS.md.

1. Scaffold · done when:
   • python -m pdftool --help lists the commands and python -m pytest runs.
   • The kit files listed under "Before you start" are still there.
2. Test files and checks · done when:
   • The fixtures open in pypdfium2 and the checks pass when a file is compared with itself.
3. Pages: split, select, reorder, rotate · done when:
   • Tests cover ranges, reordering, deleting and rotating, and the extracted text of each output page matches the source page it came from.
4. Merge · done when:
   • A test merges the bookmark file and the form file and reads back the bookmarks of the bookmark file and the field fullname with its value.
5. Compress · done when:
   • The photo fixture shrinks by at least 60% at 150 dpi and passes every check; the text fixture never grows.
6. Stamp · done when:
   • Text extracted from a stamped page contains the stamp letter for letter, in Latin and Cyrillic, and the rotated fixture shows the stamp upright and full size when rendered, with the page number at the bottom of the page as displayed.
7. Protect and unlock · done when:
   • A test protects the text fixture, fails to open it without a password, unlocks it with the right one and gets the same text back.
8. Verify · done when:
   • Every line under Definition of done is true, and anything that could not be verified is named in PROGRESS.md.

Known traps

What test builds and the official docs showed going wrong with these parts. Each one is in the brief, so the agent reads it before it gets there.

• pikepdf's pages.extend() from another file drops interactive form fields (it warns with PageCopyWarning); Pdf.add_pages_from() keeps the fields but not the bookmarks. pypdf's PdfWriter.append() kept both. measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• Keep a source Pdf open until the file you copy its pages into is saved. If the source is closed or garbage-collected first, its pages become destroyed objects and the save fails. measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• In pikepdf 10.17 page.images prints a DeprecationWarning; page.get_images() replaces it and also finds images nested inside form XObjects. measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• There is no Pdf.check(): the syntax check is pdf.check_pdf_syntax(), which returns a list of problems (empty when the file is fine). measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• After replacing an image's data with JPEG you must also set Width, Height, ColorSpace and BitsPerComponent and delete DecodeParms; otherwise the old values describe new data and viewers draw garbage. pikepdf docs and our check
• ReportLab's built-in fonts (Helvetica and the rest) have no Cyrillic: "Черновик" comes out as eight black boxes. Register a TTF font with Cyrillic, such as Inter[opsz,wght].ttf. measured with reportlab 5.0.1, Oct 12, 2026
• pypdf reads AES-encrypted PDFs (the AES-256 files protect makes) only with the extra package cryptography; without it, decrypt() raises "DependencyError: cryptography>=3.1 is required for AES algorithm". measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• pikepdf.Encryption(...) without allow= uses pikepdf.Permissions(), whose modify_assembly is False: the file forbids inserting, deleting and rotating pages. measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• add_overlay on a page with /Rotate 90 keeps the stamp upright but fits it into the page's box as stored, which is landscape when the page shows portrait: a portrait-sized stamp is scaled to 70.7% and centred. Draw the stamp at the displayed size and pass rect=Rectangle(page.mediabox). ReportLab's setPageRotation(90) swaps the stamp page's box too, so text drawn at portrait coordinates falls off it. measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026
• A PDF that has only an owner password (restrictions, no password to open) opens in pikepdf without any password, and a plain save writes it without the restrictions. measured with pikepdf 10.17.0, pypdf 6.20.1 and reportlab 5.0.1, Oct 12, 2026

Checks on this kit

• Note pikepdf 10.17.0 requires Python 3.11 or newer; the kit uses 3.12. Source

What happened when an agent built from it

The recipe was given to a fresh coding agent in a clean sandbox, twice. The agent got only the kit files. It had to build the project and write down everything in the brief that was wrong, missing or unclear.

Result of the last build. A command-line PDF tool with merge, split, reorder, rotate, compress, stamp, protect and unlock; 85 tests pass, also in a fresh clone set up from the README alone. A 29.4 MB photo PDF compressed to 298 KB at 150 dpi with the text and page sizes unchanged. Its findings went back into the recipe, which is now at v0.3. That version has not been built again as a whole.

Checked again on Oct 19, 2026. AgentGid checks every recipe each week, without a model: 6 pinned packages all still exist on their registries, 2 of them have a newer release than the tested pin; the pip lines resolve together; 19 links in the brief: all open. npm lines are checked pin by pin, not installed.

Not checked by anyone yet

• A PDF of the person's own, and how compressed files print
• The web page and the Ghostscript engine
• macOS and Windows

The kit files

Put them in an empty project folder, open your coding agent there and paste the first prompt (Claude Code first asks you to approve the MCP servers in .mcp.json). These are the files for Claude Code with the default answers; the kit builder writes them for Cursor, Codex, Copilot or another agent, and for other choices. Full guide: how to use a kit.

Download all (.zip)

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then do step 1 of the plan and stop. Report back with:
1. the commands you ran,
2. what each "Done when" check showed (a screenshot or the output),
3. anything in AGENTS.md that turned out to be wrong, missing or out of date.

Do not start step 2 until I reply.

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then work through the plan in order. After each step, run its "Done when" checks yourself and write one line in PROGRESS.md: the step, what you checked, and the result.
You may install the packages and download the files that AGENTS.md lists without asking. Stop and ask me only for what its "Before you start" section says needs a person.
When a check fails, fix the cause and run it again. If it still fails after two real fixes, stop and tell me what you tried.
Keep a list in PROGRESS.md of anything in AGENTS.md that turned out to be wrong, missing or out of date.
When every line of the Definition of done is true, stop and show me how to run it.

uv venv --seed --python 3.12 .venv && source .venv/bin/activate   # uv fetches Python 3.12 if it is missing; --seed puts pip into the venv, so the pip line below installs there and not into the system Python
# without uv: python3.12 -m venv .venv && source .venv/bin/activate
python --version   # must print 3.12.x
pip install pikepdf==10.17.0 pypdf==6.20.1 pillow==12.3.0 reportlab==5.0.1 pypdfium2==5.14.0 pytest==9.1.1

Other versions of this kit

Other versions were not test-built as a whole: the kit says which parts differ from the tested one.

Ask for this kit from your agent

Agents connected to the AgentGid MCP server get the same kit without this page: list_recipes(), then plan_project({"recipe": "pdf-tool", "answers": {"agent": "cursor"}, "files": true}). Every brief also tells the agent to ask AgentGid before it adds a part that is not listed.

Recipe pdf-tool v0.3. Data snapshot Oct 12, 2026: versions, licenses and prices change, so check the linked pages before you ship.

Comments

Other kits