Build an Evidence Pack for an AI Answer

import pymupdf
from grounding import ground_citations      # from the the grounding skill

path = "acme_report.pdf"
doc = pymupdf.open(path)
response = client.messages.create(...)      # Claude with citations enabled
results = ground_citations(response, [doc])

import hashlib
import html
from datetime import datetime, timezone

import pymupdf

from grounding import snippet, highlight

def build_evidence_pack(question, results, docs, paths, out_path):
    """Write one PDF that shows the evidence for every claim in an answer.

    results: located citations, as returned by ground_citations()
    docs, paths: the source documents and their file paths, in the same order
    """
    pack = pymupdf.open()
    width, height, margin = 595, 842, 50                  # A4 in points
    page, y = None, height

    def new_page():
        nonlocal page, y
        page, y = pack.new_page(width=width, height=height), margin

    def write(html_text, box_height=400):
        """Write HTML at the cursor and move the cursor below it."""
        nonlocal y
        rect = pymupdf.Rect(margin, y, width - margin, y + box_height)
        spare, _ = page.insert_htmlbox(rect, html_text)
        y += box_height - spare + 6

    # Cover: question, sources with fingerprints, time of creation
    new_page()
    located = sum(1 for r in results if r["quads"])
    write(f"<h2>Evidence pack</h2><p><b>Question:</b> {html.escape(question)}</p>"
          f"<p>{located} of {len(results)} citations located in the source.</p>")
    for path in paths:
        digest = hashlib.sha256(open(path, "rb").read()).hexdigest()
        write(f"<p style='font-size:9px'>Source: {html.escape(path)}<br>SHA-256: <span style='font-family:monospace'>{digest}</span></p>")
    created = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
    write(f"<p style='font-size:9px'>Created {created}</p>")

    # Render evidence images before highlighting, then add the highlighted source pages
    images = [snippet(docs, r) if r["quads"] else None for r in results]
    highlight(docs, results)
    appended = {}                                          # (doc, page) -> page in the pack

    # One entry per claim
    links = []
    for n, (r, pix) in enumerate(zip(results, images), start=1):
        needed = 120 + (pix.height * 72 / 150 if pix else 0)
        if y + needed > height - margin:
            new_page()
        found = r["quads"] != []
        status = "Found" if found else "<span style='color:#c00'>NOT FOUND, review needed</span>"
        write(f"<p><b>Claim {n}.</b> {html.escape(r['claim'])}<br>"
              f"<span style='font-size:9px'>Cited text: “{html.escape(r['cited_text'].strip())}”<br>"
              f"Status: {status}</span></p>")
        if found:
            scale = min(1, (width - 2 * margin) / (pix.width * 72 / 150))
            w, h = pix.width * 72 / 150 * scale, pix.height * 72 / 150 * scale
            img_rect = pymupdf.Rect(margin, y, margin + w, y + h)
            page.insert_image(img_rect, pixmap=pix)
            y += h + 4
            ref = f"{paths[r['doc']]}, page {r['page'] + 1}"
            write(f"<p style='font-size:9px'>{html.escape(ref)} (click the image to open the highlighted page)</p>", 30)
            links.append((page.number, img_rect, (r["doc"], r["page"])))
        y += 8

    # Append each cited source page once, with its highlights, and link to it
    for doc_index, pno in sorted({key for _, _, key in links}):
        pack.insert_pdf(docs[doc_index], from_page=pno, to_page=pno)
        appended[(doc_index, pno)] = pack.page_count - 1
    for page_number, rect, key in links:
        pack[page_number].insert_link({"kind": pymupdf.LINK_GOTO, "from": rect,
                                       "page": appended[key], "to": pymupdf.Point(0, 0)})

    pack.save(out_path, garbage=3, deflate=True)
    return out_path

from pack import build_evidence_pack

build_evidence_pack(
    "How did Acme perform in 2025, and what are the risks?",
    results, [doc], [path], "evidence_pack.pdf",
)