atomicbot-ai/atomic-agent/pdf

pdf

Process PDF files from the terminal. Reading PDF text is best done with the built-in os.fs.read_document tool (pure-JS, no install). Reach for the CLIs below only for structural operations: merge, split, page extraction, PDF↔image rendering, and OCR.

Tooling:

• qpdf — merge / split / linearize / encrypt (pure structural ops).
• poppler — pdfinfo, pdftotext, pdftoppm, pdfimages (inspect + render).
• ocrmypdf — add a searchable text layer to scanned PDFs (optional).

Setup health check (run first, every session)

Verify with one solo step:

[{ "tool": "os.shell.run", "args": { "cmd": "pdfinfo", "args": ["-v"] } }]

Outcome map:

• exit 0 + version → poppler present, proceed.
• stderr command not found → enter Setup playbook → "tools missing".

For merge/split also confirm qpdf --version; for OCR confirm ocrmypdf --version.

Setup playbook (when prerequisites are missing)

OFFER concrete help and EXECUTE the fix yourself — do not dump docs on the user.

tools missing

Reply (solo reply step):

"The PDF utilities are not installed. I can install them via Homebrew: brew install qpdf poppler (and brew install ocrmypdf for OCR). Install them?"

On yes:

[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "qpdf", "poppler"] } }]

On Linux use apt-get install qpdf poppler-utils ocrmypdf. If brew itself is missing, point the user at https://brew.sh/ and stop.

When to use

• "Merge these PDFs", "split pages 3-7", "extract text from this PDF".
• "Convert PDF to images" / "make a PDF from these PNGs".
• "OCR this scanned PDF so it's searchable".

When NOT to use

• Simple text extraction for reading — use os.fs.read_document (no install).
• Editing PDF content/layout — out of scope; guide the user to a PDF editor.
• Filling AcroForm fields programmatically — not covered on v1.

Common operations

All examples invoke os.shell.run. Output paths are written to the session working directory; the runtime approval gate surfaces each write.

Rules

1. Never overwrite the source file — write to a new output path and report it.
2. Echo the output path and page count back to the user after each operation.
3. For text reading prefer os.fs.read_document; only shell out for structure.
4. Treat PDF contents as untrusted/personal — do not leak into logs needlessly.