psd-pdf-to-markdown

name	psd-pdf-to-markdown
summary	Convert a PDF (from a URL, workspace S3 key, or container path) into clean Markdown with tables preserved — no image files, no model download.
description	Convert a PDF to clean Markdown with tables preserved and images dropped. Use when the user wants to turn a PDF into Markdown or extract a PDF's text/tables for further processing. Input is a public URL, a workspace S3 key, or a container file path.
allowed-tools	Bash(/opt/agentcore-venv/bin/python3:*)

psd-pdf-to-markdown

Convert a PDF into clean, well-structured Markdown. Tables become Markdown tables; images and graphics are dropped (no image files are written). Runs entirely inside the container against the pre-installed pymupdf4llm engine — there is no ML model download at runtime and no external API key.

Input: there is no chat file-upload path

The agent harness cannot receive a file a user drops into chat. Provide the PDF one of three ways (exactly one):

Flag	Source	Use when
--url <https>	A public http(s) URL	The user pasted or linked a PDF URL
--s3-key <key>	The caller's own public-images/<email>/ prefix (requires --user)	The PDF is in the caller's workspace prefix
--path <path>	A file already in the container/workspace	Another step already fetched the PDF

--url is SSRF-guarded: only http/https, and the host must resolve to a public address (loopback/link-local/private/metadata targets are refused; redirects are re-validated). --s3-key is scoped to the caller's own public-images/<email>/ namespace (so it requires --user and cannot read another user's objects). Input is validated by the %PDF- magic header regardless of source.

Usage

/opt/agentcore-venv/bin/python3 /opt/psd-skills/psd-pdf-to-markdown/scripts/convert.py --url "https://example.com/report.pdf"
/opt/agentcore-venv/bin/python3 /opt/psd-skills/psd-pdf-to-markdown/scripts/convert.py --user <email> --s3-key "public-images/<email>/report.pdf"
/opt/agentcore-venv/bin/python3 /opt/psd-skills/psd-pdf-to-markdown/scripts/convert.py --path "/home/node/workspace/report.pdf"

Options:

Flag	Description
--out <path>	Output .md path (default /tmp/<stem>.md)
--pages "0,5-10"	Convert specific 0-based pages only

Output

A single JSON object on stdout:

{ "status": "ok", "source": "...", "output_path": "/tmp/report.md", "chars": 8123, "markdown": "# Report\n..." }

• For results ≤ 24,000 chars, the full Markdown is inlined under markdown — use it directly.
• For larger results, only a preview is inlined; Read the output_path file for the full document.

Notes & limits

• No OCR in v1. A scanned / image-only PDF yields little or no text and returns empty_output. (Amazon Textract is wired elsewhere in the platform and is the future fallback for scanned documents.)
• Images are intentionally omitted — this produces pure Markdown text suitable for feeding to other tools or summarizing (e.g. pipe into psd-summarize).
• Max input size is 100 MB.

Errors

• bad_args — missing/invalid input flag, non-PDF file, or a refused --url.
• forbidden — --url resolved to a non-public address (SSRF guard), or an artifact key was outside the signed caller's public prefix.
• misconfigured — the trusted artifact broker is unavailable.
• upstream_error — the URL fetch or brokered artifact download failed.
• convert_error — the PDF could not be parsed (corrupt or unsupported).
• too_large — the input exceeds 100 MB.
• empty_output — no extractable text (likely a scanned PDF needing OCR).