Skip to main content

PDF evidence images for Word reports

When the agent writes a Word report based on PDF documents, it often needs to show the original passage as an image ("evidence"). This page explains how AION crops just the relevant part of the PDF page, checks the image quality and assembles a professional report. It is for administrators who enable the feature on profiles and developers who maintain the report scripts.

Problem​

Agents often embed full-page PDF screenshots (pdftoppm, convert_pdf_to_images.py) in Word reports. The result looks unprofessional compared to targeted crops with captions and document chrome (headers, deadline schedule, figure appendix).

The fix is orchestration, not a different LLM: deterministic crop via MCP, protocol rules, and optional proprietary report scripts.


MCP tool: pdf_evidence_crop​

Server: ocr (mcp_servers/ocr_mcp/). Requires AION_CHAT_SESSION_ID (session-scoped pool).

ArgumentDescription
relative_pathSession path to PDF (e.g. uploads/decreto.pdf)
page1-based page number
bboxOptional clip {x0, y0, x1, y1} in PDF points
full_pageWhen true and no bbox, skip auto-trim (still subject to white-ratio guard)
dpiRender resolution (default AION_PDF_EVIDENCE_DPI, usually 200)
captionRequired caption for the figure

Output: derived/docs/<slug>/evidence/eNNN.png + eNNN.json sidecar with page, bbox, white_ratio, cropped, caption, source_path.

Guard: if white_ratio exceeds AION_PDF_EVIDENCE_MAX_WHITE_RATIO (default 0.90), returns ok: false / too_much_whitespace so the agent cannot ship a blank full-page dump. Pages with a text layer are auto-cropped to text blocks first; sparse but real content pages get a slightly higher ceiling than blank scans.

Implementation: src/tools/pdf_evidence.py (PyMuPDF render + Pillow auto-trim).


Agent protocol​

See skill long_document_protocol (no new slug):

  1. After grep + read hits, call pdf_evidence_crop for each cited page.
  2. Never use full-page pdftoppm for evidence figures.
  3. Build Word from workspace/<slug>_findings.json + evidence PNGs.
  4. Run QA before delivery.

Skill docx documents embedding PNGs from derived/.../evidence/.


Proprietary report scripts (optional)​

After skill_view("docx"), when proprietary config is synced:

ScriptPurpose
scripts/report/build_evidence_report.pyClient-ready report: cover, executive summary, obligations overview, numbered requirements, figures, deadline schedule
scripts/report/report_style.pyNavy theme, styled tables, header/footer
scripts/report/qa_evidence_images.pyFail on high white-ratio, full-page aspect, or natural display height ≥6.5″
scripts/report/evidence_layout.pyShared max-width/max-height picture sizing for python-docx

If proprietary packages are absent, MCP + OSS protocol still apply; template scripts are best-effort.


Environment variables​

VariableDefaultDescription
AION_PDF_EVIDENCE_DPI200Default render DPI for pdf_evidence_crop
AION_PDF_EVIDENCE_MAX_WHITE_RATIO0.90Reject crops above this white pixel ratio

Eval​

CI smoke: evals/document_evidence/cases/smoke.yaml — synthetic PDF crop + sidecar checks (python -m pytest src/test/test_document_evidence_eval.py -v).