pdf-form-proof 0.1.0__py3-none-any.whl

pdf_form_proof/__init__.py

@@ -0,0 +1,3 @@
+"""pdf-form-proof: fill fillable PDF forms, then prove every value is on the page."""
+
+__version__ = "0.1.0"

pdf_form_proof/_acroform.py

@@ -0,0 +1,242 @@
+"""Low-level AcroForm helpers (pypdf). Field names, checkbox on-states,
+form-kind detection, and the /V + /AS checkbox pass.
+
+Extracted from a production form-filling server; logic unchanged.
+"""
+
+from typing import Any
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.generic import NameObject
+
+# Values treated as "do not check" for checkbox fields. Everything else
+# (True, "true", "Yes", "X", 1, "2", ...) means "set to the ON state".
+_CHECKBOX_FALSY_STRINGS = {"", "0", "off", "false", "no", "none", "unchecked"}
+
+
+def _checkbox_truthy(val: Any) -> bool:
+    if isinstance(val, bool):
+        return val
+    if val is None:
+        return False
+    if isinstance(val, (int, float)):
+        return val != 0
+    return str(val).strip().lower() not in _CHECKBOX_FALSY_STRINGS
+
+
+def _qualified_name(node) -> str | None:
+    """Fully-qualified field name (parent /T chain joined with '.'),
+    mirroring pypdf get_fields() key construction (/TM short-circuits)."""
+    try:
+        node = node.get_object()
+    except Exception:
+        pass
+    try:
+        if "/TM" in node:
+            return str(node["/TM"])
+        t = str(node["/T"]) if "/T" in node else None
+        parent = node.get("/Parent")
+        if parent is not None:
+            pname = _qualified_name(parent)
+            if t is None:
+                return pname
+            return f"{pname}.{t}" if pname else t
+        return t
+    except Exception:
+        return None
+
+
+def _widget_on_states(annot) -> list:
+    """ON-state names (without leading '/') present in a widget's /AP /N
+    (and /D) appearance dictionaries. '/Off' is excluded."""
+    states: list = []
+    try:
+        ap = annot.get("/AP")
+        if ap is None:
+            return states
+        ap = ap.get_object()
+        for ap_key in ("/N", "/D"):
+            sub = ap.get(ap_key)
+            if sub is None:
+                continue
+            sub = sub.get_object()
+            if not hasattr(sub, "keys"):
+                continue  # appearance stream, not a state dictionary
+            for k in sub.keys():
+                name = str(k)
+                if name == "/Off":
+                    continue
+                name = name[1:] if name.startswith("/") else name
+                if name not in states:
+                    states.append(name)
+    except Exception:
+        pass
+    return states
+
+
+def _btn_field_names(reader: PdfReader) -> set:
+    """Fully-qualified names of /Btn (checkbox/radio) fields in the form."""
+    names = set()
+    try:
+        fields = reader.get_fields() or {}
+    except Exception:
+        return names
+    for name, fobj in fields.items():
+        try:
+            if str(fobj.get("/FT")) == "/Btn":
+                names.add(name)
+        except Exception:
+            continue
+    return names
+
+
+def _apply_checkbox_states(writer: PdfWriter, checkbox_values: dict, on_state_map: dict) -> dict:
+    """
+    Set BOTH /V (on the field object) and /AS (on the widget annotation) for
+    checkbox/radio fields. pypdf's update_page_form_field_values set /V only,
+    so checkbox appearances did not render in some viewers.
+
+    ON-state resolution order per field:
+      (a) on_state_map -- an explicit {field: on_state} map from the caller
+          (per-field values like "1", "2", "Yes", lowercase "yes");
+      (b) else discovery from the widget /AP /N keys (first non-/Off key).
+    """
+    applied = []
+    unresolved = []
+    seen_keys = set()
+    pushbutton_flag = 1 << 16  # /Ff bit 17: pushbutton (stateless; skip)
+
+    for page in writer.pages:
+        annots = page.get("/Annots")
+        if not annots:
+            continue
+        for ref in annots:
+            try:
+                annot = ref.get_object()
+            except Exception:
+                continue
+            if annot.get("/Subtype") != "/Widget":
+                continue
+            # Resolve the owning field node (where /FT and /V live).
+            field_node = annot
+            ftype = field_node.get("/FT")
+            hops = 0
+            while ftype is None and field_node.get("/Parent") is not None and hops < 16:
+                field_node = field_node["/Parent"].get_object()
+                ftype = field_node.get("/FT")
+                hops += 1
+            if str(ftype) != "/Btn":
+                continue
+            try:
+                flags = int(field_node.get("/Ff", 0) or 0)
+            except Exception:
+                flags = 0
+            if flags & pushbutton_flag:
+                continue
+
+            fq = (_qualified_name(annot) or "").rstrip(".")
+            matched_key = None
+            if fq and fq in checkbox_values:
+                matched_key = fq
+            elif fq:
+                # Backslash-insensitive fallback: XFA-shadow leaf names carry
+                # literal backslash-dot sequences (e.g. List17\.1[0]).
+                fq_plain = fq.replace("\\", "")
+                for k in checkbox_values:
+                    if k.replace("\\", "") == fq_plain:
+                        matched_key = k
+                        break
+            if matched_key is None:
+                continue
+
+            val = checkbox_values[matched_key]
+            widget_states = _widget_on_states(annot)
+            if _checkbox_truthy(val):
+                target = str(on_state_map.get(matched_key) or "").lstrip("/")
+                if not target:
+                    target = widget_states[0] if widget_states else ""
+                if not target:
+                    if matched_key not in seen_keys:
+                        unresolved.append(matched_key)
+                        seen_keys.add(matched_key)
+                    continue
+                state = NameObject("/" + target)
+                # /AS only where this widget owns the target state (radio
+                # kids each own a single state); other kids go /Off.
+                if not widget_states or target in widget_states:
+                    annot[NameObject("/AS")] = state
+                else:
+                    annot[NameObject("/AS")] = NameObject("/Off")
+                field_node[NameObject("/V")] = state
+                applied.append({"field": matched_key, "state": "/" + target})
+            else:
+                annot[NameObject("/AS")] = NameObject("/Off")
+                field_node[NameObject("/V")] = NameObject("/Off")
+                applied.append({"field": matched_key, "state": "/Off"})
+            seen_keys.add(matched_key)
+
+    no_match = [k for k in checkbox_values if k not in seen_keys]
+    return {"applied": applied, "unresolved_on_state": unresolved, "no_widget_match": no_match}
+
+
+def detect_form_kind(pdf_path: str) -> str:
+    """
+    Return 'acroform', 'xfa', or 'none' based on PDF structure.
+    XFA: has /AcroForm/XFA entry (Adobe LiveCycle dynamic forms).
+    AcroForm: has /AcroForm/Fields with non-empty fields list.
+    """
+    try:
+        reader = PdfReader(pdf_path)
+    except Exception:
+        return "none"
+    root = reader.trailer.get("/Root", {})
+    acroform = None
+    try:
+        acroform = root.get("/AcroForm")
+    except Exception:
+        acroform = None
+    if not acroform:
+        return "none"
+    try:
+        acro_obj = acroform.get_object() if hasattr(acroform, "get_object") else acroform
+    except Exception:
+        acro_obj = acroform
+    has_xfa = False
+    has_fields = False
+    try:
+        if "/XFA" in acro_obj:
+            has_xfa = True
+        if "/Fields" in acro_obj:
+            fields = acro_obj.get("/Fields")
+            if fields and len(fields) > 0:
+                has_fields = True
+    except Exception:
+        pass
+    if has_xfa and not has_fields:
+        return "xfa"
+    if has_fields and not has_xfa:
+        return "acroform"
+    if has_fields and has_xfa:
+        # Hybrid XFA -- pypdf may fill the AcroForm shadow fields successfully
+        return "acroform"
+    return "none"
+
+
+def list_acroform_fields(pdf_path: str) -> list[dict]:
+    """
+    Walk AcroForm fields and return [{name, type, value, flags, is_required}, ...].
+    For XFA-only forms, returns empty list (caller should switch to xfa_handler).
+    """
+    reader = PdfReader(pdf_path)
+    fields = reader.get_fields() or {}
+    out = []
+    for name, fobj in fields.items():
+        ftype = fobj.get("/FT")
+        out.append({
+            "name": name,
+            "type": str(ftype) if ftype else "unknown",
+            "value": fobj.get("/V"),
+            "flags": fobj.get("/Ff"),
+            "is_required": bool(fobj.get("/Ff") and int(fobj.get("/Ff", 0)) & 2),
+        })
+    return out

pdf_form_proof/cli.py

@@ -0,0 +1,37 @@
+"""Command-line entry points: pdf-form-inspect, pdf-form-fill, pdf-form-verify."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .fill import fill_form, inspect_form
+from .legibility import main as verify_main
+
+
+def inspect_main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="List fillable fields in a PDF form.")
+    ap.add_argument("pdf")
+    a = ap.parse_args(argv)
+    print(json.dumps(inspect_form(a.pdf), indent=2))
+    return 0
+
+
+def fill_main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Fill a PDF form from a JSON file of {field: value}.")
+    ap.add_argument("source_pdf")
+    ap.add_argument("output_pdf")
+    ap.add_argument("values_json")
+    ap.add_argument("--loose", action="store_true", help="skip unknown field names instead of refusing")
+    ap.add_argument("--finalize", action="store_true")
+    a = ap.parse_args(argv)
+    with open(a.values_json, encoding="utf-8") as f:
+        values = json.load(f)
+    res = fill_form(a.source_pdf, a.output_pdf, values, strict=not a.loose, finalize=a.finalize)
+    print(json.dumps(res, indent=2))
+    return 0 if res.get("status") == "ok" else (2 if res.get("status") == "refused" else 1)
+
+
+if __name__ == "__main__":
+    sys.exit(verify_main())

pdf_form_proof/fill.py

@@ -0,0 +1,195 @@
+"""Inspect and fill AcroForm PDF forms, refusing anything it cannot apply.
+
+Rules this module keeps:
+  - The source PDF is never modified. Output goes to a new path, and an
+    existing output file is never overwritten.
+  - Strict by default: if any requested field name does not exist in the
+    form, nothing is written and the unknown names are returned. A partial
+    fill is never hidden behind a success message.
+  - Checkbox and radio fields get both /V and the widget /AS set, so the
+    check mark renders instead of only existing in the data.
+  - Every written file is returned with its SHA-256.
+
+Limit: XFA-only forms (Adobe LiveCycle dynamic forms with no AcroForm
+fields) are detected and refused; this module does not fill XFA.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from pypdf import PdfReader, PdfWriter
+
+from ._acroform import (
+    _apply_checkbox_states,
+    _btn_field_names,
+    _widget_on_states,
+    _qualified_name,
+    detect_form_kind,
+)
+
+# pypdf logs a warning per page with no fields; keep stdio clean for MCP.
+logging.getLogger("pypdf").setLevel(logging.ERROR)
+
+
+def sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _button_on_states(reader: PdfReader) -> dict[str, list[str]]:
+    """{qualified field name: [on-state names]} for checkbox/radio widgets."""
+    out: dict[str, list[str]] = {}
+    for page in reader.pages:
+        for ref in page.get("/Annots") or []:
+            try:
+                annot = ref.get_object()
+            except Exception:
+                continue
+            if annot.get("/Subtype") != "/Widget":
+                continue
+            states = _widget_on_states(annot)
+            if not states:
+                continue
+            name = (_qualified_name(annot) or "").rstrip(".")
+            if not name:
+                continue
+            for s in states:
+                out.setdefault(name, [])
+                if s not in out[name]:
+                    out[name].append(s)
+    return out
+
+
+def inspect_form(pdf_path: str) -> dict[str, Any]:
+    """Return the form kind and every fillable field with its type and,
+    for checkboxes and radios, the on-state values that will check them."""
+    kind = detect_form_kind(pdf_path)
+    if kind != "acroform":
+        return {"pdf_path": pdf_path, "kind": kind, "field_count": 0, "fields": [],
+                "note": ("XFA-only form: this tool does not fill XFA."
+                         if kind == "xfa" else "No AcroForm fields found.")}
+    reader = PdfReader(pdf_path)
+    fields = reader.get_fields() or {}
+    on_states = _button_on_states(reader)
+    out = []
+    for name, fobj in fields.items():
+        ftype = fobj.get("/FT")
+        if ftype is None:
+            continue  # container node, not a fillable field
+        entry = {
+            "name": name,
+            "type": {"/Tx": "text", "/Btn": "button", "/Ch": "choice",
+                     "/Sig": "signature"}.get(str(ftype), str(ftype)),
+            "value": None if fobj.get("/V") is None else str(fobj.get("/V")),
+            "required": bool(fobj.get("/Ff") and int(fobj.get("/Ff", 0)) & 2),
+        }
+        if str(ftype) == "/Btn":
+            entry["on_states"] = ["/" + s for s in on_states.get(name, [])]
+        if str(ftype) == "/Ch" and fobj.get("/Opt") is not None:
+            entry["options"] = [str(o) for o in fobj.get("/Opt")]
+        out.append(entry)
+    return {"pdf_path": pdf_path, "kind": kind, "field_count": len(out), "fields": out}
+
+
+def fill_form(source_pdf_path: str, output_path: str, values: dict[str, Any],
+              strict: bool = True, finalize: bool = False) -> dict[str, Any]:
+    """Fill fields by exact qualified name.
+
+    values: {field name: value}. Text fields take a string. Checkbox/radio
+    fields take an on-state ("/1", "/Yes") or True to check, and "", False,
+    or "Off" to clear.
+
+    finalize=True removes any /XFA packet and the /NeedAppearances flag so
+    viewers render the values from their own appearance streams. It does NOT
+    flatten the form: fields stay editable.
+    """
+    if not os.path.isfile(source_pdf_path):
+        return {"status": "refused", "reason": f"no such file: {source_pdf_path}"}
+    if os.path.abspath(source_pdf_path) == os.path.abspath(output_path):
+        return {"status": "refused", "reason": "output_path equals source; the source is never modified"}
+    if os.path.exists(output_path):
+        return {"status": "refused", "reason": f"output exists, not overwritten: {output_path}"}
+    kind = detect_form_kind(source_pdf_path)
+    if kind != "acroform":
+        return {"status": "refused", "reason": f"form kind is {kind!r}; only AcroForm forms are filled"}
+
+    reader = PdfReader(source_pdf_path)
+    known = set((reader.get_fields() or {}).keys())
+    unknown = sorted(k for k in values if k not in known)
+    if unknown and strict:
+        return {"status": "refused", "reason": "field names not in this form; nothing written",
+                "unknown_fields": unknown,
+                "hint": "run pdf_form_inspect and copy names exactly"}
+
+    writer = PdfWriter(clone_from=reader)
+    btn_names = _btn_field_names(reader)
+    checkbox_values: dict = {}
+    text_values: dict = {}
+    for name, val in values.items():
+        if name not in known:
+            continue
+        if name in btn_names:
+            if isinstance(val, str) and val.strip().lower() in ("off", "/off"):
+                val = ""
+            checkbox_values[name] = val
+        else:
+            text_values[name] = "" if val is None else str(val)
+
+    pages_touched = 0
+    if text_values:
+        for page in writer.pages:
+            try:
+                writer.update_page_form_field_values(page, text_values)
+                pages_touched += 1
+            except Exception:
+                continue
+
+    on_map = {k: str(v).lstrip("/") for k, v in checkbox_values.items()
+              if isinstance(v, str) and v.startswith("/")}
+    cb = _apply_checkbox_states(writer, checkbox_values, on_map)
+
+    finalize_changes = []
+    if finalize:
+        try:
+            acro = writer._root_object.get("/AcroForm")
+            if acro is not None:
+                acro = acro.get_object() if hasattr(acro, "get_object") else acro
+                if "/XFA" in acro:
+                    del acro["/XFA"]
+                    finalize_changes.append("removed /XFA")
+                if "/NeedAppearances" in acro:
+                    del acro["/NeedAppearances"]
+                    finalize_changes.append("removed /NeedAppearances")
+        except Exception as e:  # report, do not hide
+            finalize_changes.append(f"finalize error: {e}")
+
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "wb") as f:
+        writer.write(f)
+
+    # Read back: every text value must be present on the written file.
+    back = PdfReader(output_path).get_fields() or {}
+    mismatched = [k for k, v in text_values.items()
+                  if str(back.get(k, {}).get("/V", "")) != v]
+    status = "ok" if not (mismatched or cb["unresolved_on_state"] or cb["no_widget_match"]) else "incomplete"
+    return {
+        "status": status,
+        "output_path": output_path,
+        "sha256": sha256_file(output_path),
+        "text_fields_set": len(text_values) - len(mismatched),
+        "text_fields_not_read_back": mismatched,
+        "checkboxes_set": cb["applied"],
+        "checkbox_unresolved_on_state": cb["unresolved_on_state"],
+        "checkbox_no_widget_match": cb["no_widget_match"],
+        "unknown_fields_skipped": unknown,
+        "finalize": finalize_changes if finalize else "not requested",
+        "next_step": "run pdf_form_verify on the output to prove the values render",
+    }

pdf_form_proof/legibility.py

@@ -0,0 +1,262 @@
+"""Prove that filled values are visible on the rendered page, not only
+present in the PDF's hidden text layer.
+
+Why: a PDF can carry a value in its data while the page a person sees (or
+prints, or a reviewer opens) shows nothing, or shows it clipped. Every
+text-based check passes on such a file. This check compares two channels:
+
+  in text layer   seen by OCR of the render   verdict
+  -------------   --------------------------  -----------------------------
+  yes             yes                         VISIBLE
+  yes             no                          INVISIBLE (in the file, not on the page)
+  no              yes                         RENDER-ONLY (on the page, not in the data)
+  no              no                          MISSING
+
+Region scoping: pass a region (x0,y0,x1,y1 as fractions of the page) and only
+that band is OCRd, so a copy of the value elsewhere on the page cannot make it
+pass. With a region, "auto" mode also demands that every word the text layer
+places inside the region is legible in the render, so the caller does not
+have to remember which values to check.
+
+Fail-closed rules: if pdftotext, pdftoppm or tesseract fails, the result is
+REFUSE with the tool's own error, never a finding about the document. An
+empty OCR result from a broken engine is not evidence a value is missing.
+
+Limit: this proves legibility only. It says nothing about whether the values
+are correct, complete, or appropriate for the form's purpose.
+
+Requires the poppler utilities (pdftotext, pdftoppm) and the tesseract
+binary on PATH. Region scoping also needs Pillow.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from typing import Any
+
+
+def norm(s: str) -> str:
+    """Collapse to a comparable form: OCR confuses case, spacing and punctuation."""
+    s = s.upper().replace("&", "AND")
+    return re.sub(r"[^A-Z0-9]", "", s)
+
+
+class _Refusal(str):
+    """An empty result that carries the reason it is empty."""
+
+    def __new__(cls, reason):
+        s = super().__new__(cls, "")
+        s.reason = reason
+        return s
+
+
+def _missing_binaries() -> list[str]:
+    return [b for b in ("pdftotext", "pdftoppm", "tesseract") if shutil.which(b) is None]
+
+
+def region_words(pdf: str, page: int, region) -> list[str] | None:
+    """Words the text layer places fully inside the region (the auto set)."""
+    try:
+        out = subprocess.run(["pdftotext", "-bbox", "-f", str(page), "-l", str(page), pdf, "-"],
+                             capture_output=True, timeout=120)
+    except Exception:
+        return None
+    if out.returncode != 0:
+        return None
+    xml = out.stdout.decode("utf-8", "replace")
+    pm = re.search(r'<page width="([\d.]+)" height="([\d.]+)"', xml)
+    if not pm:
+        return None
+    PW, PH = float(pm.group(1)), float(pm.group(2))
+    x0, y0, x1, y1 = region
+    X0, Y0, X1, Y1 = x0 * PW, y0 * PH, x1 * PW, y1 * PH
+    words = []
+    for wx0, wy0, wx1, wy1, w in re.findall(
+            r'<word xMin="([\d.]+)" yMin="([\d.]+)" xMax="([\d.]+)" yMax="([\d.]+)">([^<]*)</word>', xml):
+        # Full containment: a word straddling the edge would be sliced by the
+        # crop and reported invisible when it is only half-photographed.
+        if X0 <= float(wx0) and float(wx1) <= X1 and Y0 <= float(wy0) and float(wy1) <= Y1:
+            t = w.replace("&amp;", "&").replace("&lt;", "<").replace("&gt;", ">").strip()
+            if t:
+                words.append(t)
+    return words
+
+
+def text_layer(pdf: str, page: int):
+    try:
+        out = subprocess.run(["pdftotext", "-layout", "-f", str(page), "-l", str(page), pdf, "-"],
+                             capture_output=True, timeout=120)
+    except Exception as e:
+        return _Refusal(f"pdftotext could not run: {e}")
+    if out.returncode != 0:
+        return _Refusal(f"pdftotext exited {out.returncode}")
+    return out.stdout.decode("utf-8", "replace")
+
+
+def render_ocr(pdf: str, page: int, dpi: int = 300, region=None):
+    """Render the page and OCR it. Returns (text or _Refusal or None, png path)."""
+    cache = os.path.expanduser("~/.cache/pdf-form-proof")
+    os.makedirs(cache, exist_ok=True)
+    for old in glob.glob(os.path.join(cache, "render_*")):
+        shutil.rmtree(old, ignore_errors=True)
+    d = tempfile.mkdtemp(prefix="render_", dir=cache)
+    stem = os.path.join(d, "p")
+    rr = subprocess.run(["pdftoppm", "-png", "-r", str(dpi), "-f", str(page), "-l", str(page), pdf, stem],
+                        capture_output=True, timeout=300)
+    pngs = [os.path.join(d, f) for f in sorted(os.listdir(d)) if f.endswith(".png")]
+    if rr.returncode != 0:
+        e = next((x for x in rr.stderr.decode("utf-8", "replace").splitlines() if x.strip()), "(no stderr)")
+        return _Refusal(f"pdftoppm exited {rr.returncode}; the page was never rendered: {e.strip()[:120]}"), None
+    if not pngs:
+        return _Refusal(f"pdftoppm exited 0 but produced no image for page {page}"), None
+    png = pngs[0]
+    if region:
+        try:
+            from PIL import Image
+        except Exception:
+            return None, png  # caller refuses: no silent whole-page fallback
+        img = Image.open(png)
+        W, H = img.size
+        x0, y0, x1, y1 = region
+        px, py = 0.02, 0.01  # pad the crop so a boundary glyph keeps its whole body
+        img = img.crop((max(0, int((x0 - px) * W)), max(0, int((y0 - py) * H)),
+                        min(W, int((x1 + px) * W)), min(H, int((y1 + py) * H))))
+        img.save(png)
+    # The tesseract binary is used directly; a Python wrapper was observed to
+    # return an empty string with no error on one interpreter.
+    r = subprocess.run(["tesseract", png, "stdout"], capture_output=True, timeout=300)
+    if r.returncode != 0:
+        e = next((x for x in r.stderr.decode("utf-8", "replace").splitlines() if x.strip()), "(no stderr)")
+        return _Refusal(f"tesseract exited {r.returncode}; OCR never read the page: {e.strip()[:120]}"), png
+    return r.stdout.decode("utf-8", "replace"), png
+
+
+def parse_region(region):
+    if region is None or (isinstance(region, str) and region.strip().lower() in ("", "page")):
+        return None
+    if isinstance(region, str):
+        region = [float(x) for x in region.split(",")]
+    region = tuple(float(x) for x in region)
+    if len(region) != 4 or not all(0.0 <= v <= 1.0 for v in region):
+        raise ValueError("region must be four fractions x0,y0,x1,y1 between 0 and 1")
+    return region
+
+
+def check_legibility(pdf: str, require: list[str] | None = None, page: int = 1,
+                     region=None, auto: bool = True, dpi: int = 300,
+                     ignore_words: list[str] | None = None,
+                     keep_render: str | None = None) -> dict[str, Any]:
+    """Return {"verdict": PASS|REFUSE, "rows": [...], ...}. Exit-code mapping
+    for the CLI: PASS 0, a finding against the document 1, a tool failure 2."""
+    require = [r for r in (require or []) if r and r.strip()]
+    if not os.path.isfile(pdf):
+        return {"verdict": "REFUSE", "kind": "usage", "reason": f"no such file: {pdf}"}
+    missing = _missing_binaries()
+    if missing:
+        return {"verdict": "REFUSE", "kind": "tool_failure",
+                "reason": "missing required programs: " + ", ".join(missing),
+                "install": "macOS: brew install poppler tesseract; Debian/Ubuntu: apt install poppler-utils tesseract-ocr"}
+    try:
+        reg = parse_region(region)
+    except Exception as e:
+        return {"verdict": "REFUSE", "kind": "usage", "reason": str(e)}
+
+    tl_raw = text_layer(pdf, page)
+    if isinstance(tl_raw, _Refusal):
+        return {"verdict": "REFUSE", "kind": "tool_failure", "reason": tl_raw.reason}
+    ocr_raw, png = render_ocr(pdf, page, dpi, reg)
+    if isinstance(ocr_raw, _Refusal):
+        return {"verdict": "REFUSE", "kind": "tool_failure", "reason": ocr_raw.reason,
+                "note": "no legibility finding is made; an empty OCR result is not evidence"}
+    if ocr_raw is None:
+        return {"verdict": "REFUSE", "kind": "tool_failure",
+                "reason": "region scoping needs Pillow (pip install pillow), or pass region='page'"}
+
+    auto_words: list[str] = []
+    if auto and reg:
+        got = region_words(pdf, page, reg)
+        if got is None:
+            return {"verdict": "REFUSE", "kind": "tool_failure",
+                    "reason": "could not read the text layer to derive the auto requirement set"}
+        skip = {w.lower() for w in (ignore_words or [])}
+        auto_words = [w for w in got if w.lower() not in skip]
+
+    checks = [(w, "auto") for w in auto_words] + [(w, "required") for w in require]
+    if not checks:
+        return {"verdict": "REFUSE", "kind": "usage",
+                "reason": "nothing to check: give values in 'require', or a region with text for auto mode"}
+
+    tl, ocr = norm(tl_raw), norm(ocr_raw)
+    rows, refuse = [], False
+    for want, origin in checks:
+        n = norm(want)
+        if not n:
+            continue
+        in_text, in_ocr = n in tl, n in ocr
+        if in_text and in_ocr:
+            v = "VISIBLE"
+        elif in_text:
+            v = "INVISIBLE"; refuse = True
+        elif in_ocr:
+            v = "RENDER-ONLY"; refuse = True
+        else:
+            v = "MISSING"; refuse = True
+        rows.append({"value": want, "source": origin, "in_text_layer": in_text,
+                     "in_render": in_ocr, "verdict": v})
+    kept = None
+    if keep_render and png:
+        try:
+            shutil.copy2(png, keep_render)
+            kept = keep_render
+        except Exception:
+            kept = None
+    return {
+        "verdict": "REFUSE" if refuse else "PASS",
+        "kind": "finding" if refuse else "pass",
+        "file": pdf, "page": page, "dpi": dpi,
+        "scope": f"region {reg}" if reg else "whole page",
+        "rows": rows,
+        "auto_values": len(auto_words), "required_values": len(require),
+        "render_kept": kept,
+        "limit": "legibility only; says nothing about whether values are correct",
+    }
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Prove filled PDF values are visible on the rendered page.")
+    ap.add_argument("pdf")
+    ap.add_argument("--require", action="append", default=[], help="a value that must be legible")
+    ap.add_argument("--page", type=int, default=1)
+    ap.add_argument("--dpi", type=int, default=300)
+    ap.add_argument("--region", default="page", help="x0,y0,x1,y1 as page fractions, or 'page'")
+    ap.add_argument("--no-auto", action="store_true", help="only check --require values")
+    ap.add_argument("--keep-render", default=None, help="copy the rendered PNG here")
+    a = ap.parse_args(argv)
+    res = check_legibility(a.pdf, a.require, a.page, a.region, not a.no_auto, a.dpi,
+                           keep_render=a.keep_render)
+    print(f"PDF FORM PROOF - legibility check  verdict: {res['verdict']}")
+    for k in ("reason", "install", "note"):
+        if k in res:
+            print(f"  {k}: {res[k]}")
+    if res.get("rows"):
+        print(f"  file: {os.path.basename(a.pdf)}  page {res['page']} at {res['dpi']} dpi  scope: {res['scope']}")
+        w = max(len(r["value"]) for r in res["rows"])
+        print(f"  {'VALUE':<{w}}  SOURCE    TEXT  RENDER  VERDICT")
+        for r in res["rows"]:
+            print(f"  {r['value']:<{w}}  {r['source']:<8}  {'yes' if r['in_text_layer'] else 'no':<4}  "
+                  f"{'yes' if r['in_render'] else 'no':<6}  {r['verdict']}")
+        print(f"  limit: {res['limit']}")
+    if res["verdict"] == "PASS":
+        return 0
+    return 1 if res.get("kind") == "finding" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pdf_form_proof/server.py

@@ -0,0 +1,97 @@
+"""MCP server (stdio) for pdf-form-proof.
+
+Tools:
+  pdf_form_inspect  - list every fillable field, its type, and checkbox on-states
+  pdf_form_fill     - fill by exact field name; refuses unknown names; never overwrites
+  pdf_form_verify   - prove the values are visible on the rendered page (OCR vs text layer)
+  pdf_sha256        - SHA-256 of a file, for a record of exactly what was produced
+
+Everything runs locally. No network calls, no API keys, no telemetry.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from . import __version__
+from .fill import fill_form, inspect_form, sha256_file
+from .legibility import check_legibility
+
+mcp = FastMCP(
+    "pdf-form-proof",
+    instructions=(
+        "Fill fillable (AcroForm) PDF forms and prove the result. Workflow: "
+        "1) pdf_form_inspect to get exact field names and checkbox on-states; "
+        "2) pdf_form_fill with those exact names (unknown names are refused, nothing written); "
+        "3) pdf_form_verify with the filled values to confirm each one is visible on the "
+        "rendered page, not only stored in the file. Report REFUSE verdicts to the user as-is. "
+        "This tool fills forms; it does not give legal, tax, or benefits advice."
+    ),
+)
+
+
+@mcp.tool(
+    title="Inspect PDF form fields",
+    annotations=ToolAnnotations(title="Inspect PDF form fields", readOnlyHint=True,
+                                destructiveHint=False, openWorldHint=False),
+)
+def pdf_form_inspect(pdf_path: str) -> dict[str, Any]:
+    """List every fillable field in a PDF: exact name, type (text, button, choice,
+    signature), current value, required flag, and for checkboxes/radios the on-state
+    values that check them. Use the names exactly as returned when filling."""
+    return inspect_form(pdf_path)
+
+
+@mcp.tool(
+    title="Fill PDF form",
+    annotations=ToolAnnotations(title="Fill PDF form", readOnlyHint=False,
+                                destructiveHint=False, idempotentHint=False, openWorldHint=False),
+)
+def pdf_form_fill(source_pdf_path: str, output_path: str, values: dict[str, Any],
+                  strict: bool = True, finalize: bool = False) -> dict[str, Any]:
+    """Fill an AcroForm PDF and write a NEW file (the source is never modified and an
+    existing output is never overwritten). values maps exact field names to values:
+    strings for text fields; an on-state such as "/1" or "/Yes" (or true) to check a box,
+    "" or false to clear it. strict=true refuses the whole fill if any name is unknown.
+    finalize=true removes the XFA packet and NeedAppearances flag so viewers render the
+    values from their own appearance streams (fields stay editable; this is not flattening).
+    Returns the output SHA-256 and a read-back of every text value."""
+    return fill_form(source_pdf_path, output_path, values, strict=strict, finalize=finalize)
+
+
+@mcp.tool(
+    title="Verify filled values are visible",
+    annotations=ToolAnnotations(title="Verify filled values are visible", readOnlyHint=True,
+                                destructiveHint=False, openWorldHint=False),
+)
+def pdf_form_verify(pdf_path: str, values: list[str] | None = None, page: int = 1,
+                    region: str = "page", auto: bool = True, dpi: int = 300) -> dict[str, Any]:
+    """Render one page, OCR it, and compare with the PDF text layer. Each value gets a
+    verdict: VISIBLE, INVISIBLE (in the file but not on the page), RENDER-ONLY, or MISSING.
+    region is "page" or "x0,y0,x1,y1" as page fractions; with a region and auto=true every
+    word the text layer places in that region must also be legible. A tool failure
+    (missing poppler or tesseract, render error) returns REFUSE with the reason and makes
+    no finding about the document. Proves legibility only, not correctness."""
+    return check_legibility(pdf_path, require=values or [], page=page, region=region,
+                            auto=auto, dpi=dpi)
+
+
+@mcp.tool(
+    title="SHA-256 of a file",
+    annotations=ToolAnnotations(title="SHA-256 of a file", readOnlyHint=True,
+                                destructiveHint=False, openWorldHint=False),
+)
+def pdf_sha256(path: str) -> dict[str, Any]:
+    """Return the SHA-256 digest of a file so the exact output can be recorded."""
+    return {"path": path, "sha256": sha256_file(path), "server_version": __version__}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pdf_form_proof-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: pdf-form-proof
+Version: 0.1.0
+Summary: Fill fillable PDF forms, then prove every value is visible on the rendered page. MCP server and CLI.
+Project-URL: Homepage, https://github.com/EssenceAlignment/pdf-form-proof
+Project-URL: Issues, https://github.com/EssenceAlignment/pdf-form-proof/issues
+Author: EssenceAlignment
+License: MIT
+License-File: LICENSE
+Keywords: acroform,form-filling,mcp,nonprofit,ocr,pdf,pdf-form,verification
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.10
+Requires-Dist: pillow>=10.0
+Requires-Dist: pypdf>=4.0
+Description-Content-Type: text/markdown
+
+# pdf-form-proof
+
+Fill a fillable PDF form, then prove every value actually shows on the page.
+
+mcp-name: io.github.EssenceAlignment/pdf-form-proof
+
+A PDF can hold a value in its data while the page a person sees, prints, or
+uploads shows nothing, or shows it cut off. Most form tools stop at "the field
+was set." This one keeps going: it renders the page, reads it back with OCR
+(optical character recognition, software that reads text from an image), and
+compares that with the text stored in the file. Each value comes back VISIBLE,
+INVISIBLE, RENDER-ONLY, or MISSING.
+
+It works as an MCP server (MCP, the Model Context Protocol, is the plug-in
+standard that lets AI apps such as Claude call outside tools), as a Claude
+plugin, as a Gemini CLI extension, and as plain command-line tools.
+
+## What it does
+
+| Tool | What it does | Changes files? |
+|---|---|---|
+| `pdf_form_inspect` | Lists every fillable field: exact name, type, current value, required flag, and the values that check each checkbox or radio button | No |
+| `pdf_form_fill` | Fills fields by exact name and writes a new PDF. Refuses the whole fill if any name is not in the form. Never modifies the source, never overwrites an existing file. Returns the new file's SHA-256 and reads every text value back | Writes one new file |
+| `pdf_form_verify` | Renders a page, OCRs it, and gives each value a verdict. Can be limited to one region of the page so a copy of the value elsewhere cannot make it pass | No |
+| `pdf_sha256` | SHA-256 fingerprint of a file, for a record of exactly what was produced | No |
+
+Every tool carries MCP annotations: `readOnlyHint` and `destructiveHint` are set on all four.
+
+## Who it is for
+
+Anyone who fills the same official PDFs again and again: small nonprofits and
+community organizations (vendor forms such as the IRS W-9, grant and funder
+forms, program intake and consent forms), operations staff, and builders who
+want an AI assistant to fill forms without hiding a partial or invisible fill.
+
+## Install
+
+You need Python 3.10 or newer and `uv` (https://docs.astral.sh/uv/). The verify
+tool also needs two free programs:
+
+- macOS: `brew install poppler tesseract`
+- Debian or Ubuntu: `sudo apt install poppler-utils tesseract-ocr`
+
+### Claude Desktop (MCP server)
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pdf-form-proof": {
+      "command": "uvx",
+      "args": ["pdf-form-proof"]
+    }
+  }
+}
+```
+
+Or install the `.mcpb` file from the latest GitHub release: double-click it, or
+use Settings > Extensions > Advanced settings > Install Extension.
+
+### Claude Code (plugin)
+
+```
+claude plugin marketplace add EssenceAlignment/pdf-form-proof
+claude plugin install pdf-form-proof@pdf-form-proof
+```
+
+### Gemini CLI (extension)
+
+```
+gemini extensions install https://github.com/EssenceAlignment/pdf-form-proof
+```
+
+### Command line
+
+```
+uvx --from pdf-form-proof pdf-form-inspect form.pdf
+uvx --from pdf-form-proof pdf-form-fill form.pdf filled.pdf values.json
+uvx --from pdf-form-proof pdf-form-verify filled.pdf --require "Sample Community Food Bank"
+```
+
+`values.json` maps exact field names (from `pdf-form-inspect`) to values:
+
+```json
+{
+  "topmostSubform[0].Page1[0].f1_01[0]": "Sample Community Food Bank",
+  "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[0]": "/1"
+}
+```
+
+Text fields take a string. A checkbox or radio takes one of its on-state values
+(shown by inspect, for example "/1" or "/Yes"), or an empty string to clear it.
+
+Exit codes: 0 success; 1 a finding (verify found a value that is not visible,
+or a fill could not be read back); 2 refused (unknown field names, a missing
+file, an existing output, or a tool such as tesseract failed).
+
+## Example
+
+```
+$ pdf-form-verify filled.pdf --require "Sample Community Food Bank" --require "Sample Pantry Program"
+PDF FORM PROOF - legibility check  verdict: PASS
+  file: filled.pdf  page 1 at 300 dpi  scope: whole page
+  VALUE                       SOURCE    TEXT  RENDER  VERDICT
+  Sample Community Food Bank  required  yes   yes     VISIBLE
+  Sample Pantry Program       required  yes   yes     VISIBLE
+  limit: legibility only; says nothing about whether values are correct
+```
+
+## Limits (read these)
+
+- AcroForm forms only. XFA-only forms (Adobe LiveCycle dynamic forms) are
+  detected and refused, not filled.
+- `finalize` removes the XFA packet and the NeedAppearances flag so viewers draw
+  the values from their own appearance streams. It does not flatten the form;
+  fields stay editable.
+- Verify proves legibility, not correctness. It cannot tell you whether a value
+  is the right answer for the form.
+- OCR can misread small, stylized, or handwritten-style fonts. A REFUSE verdict
+  means "look at the page," not "the file is broken." A tool failure (missing
+  poppler or tesseract, a render error) is reported as a tool failure, never as
+  a finding about your document.
+- Signatures are not created. Signature fields are listed by inspect and left alone.
+- This tool fills forms. It does not give legal, tax, benefits, or other
+  professional advice, and it does not decide what belongs in any field.
+
+## Privacy policy
+
+pdf-form-proof runs entirely on your own computer.
+
+- Data collection: none. It reads only the PDF files you name and writes only
+  the output path you name.
+- Usage and storage: rendered page images are kept in `~/.cache/pdf-form-proof`
+  only until the next verify run, which deletes them.
+- Third-party sharing: none. It makes no network calls and sends no telemetry.
+- Retention: nothing is retained beyond the files you create.
+- Contact: open an issue at https://github.com/EssenceAlignment/pdf-form-proof/issues
+
+## Origin
+
+The fill engine and the visible-on-the-page check were built for a production
+document pipeline after a filled form passed every text-based check and was
+still returned because a value could not be seen on the page. The two rules
+that came out of that: never hide a partial fill, and check the page a person
+sees, not only the data in the file.
+
+## License
+
+MIT. See `LICENSE`.

pdf_form_proof-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pdf_form_proof/__init__.py,sha256=hfq_9_Y9ooxdAk13GraNyPTiea8ZrixrmCSLlZZFEp0,109
+pdf_form_proof/_acroform.py,sha256=TjQl-YFcHwt_ClfNwfyb93qtkTWe6NDOWCtBjZ97JIU,8538
+pdf_form_proof/cli.py,sha256=_EkDQ34zXzYTxY8Ftsh5Kj0sBSwx1f5YoYf_ajUYGS8,1281
+pdf_form_proof/fill.py,sha256=caBqAxcJR8EEWAoPGWzSoPVUwu006A9jlKNdMutyUAg,7937
+pdf_form_proof/legibility.py,sha256=o1-1BvoEaJmUztzqzklEd49Nm6NuYSe4C5xTC4WN5tI,11735
+pdf_form_proof/server.py,sha256=TizEJKhEVoU0SZL5RZIjsVJutnsXnMMbF6RRNqfdxbI,4501
+pdf_form_proof-0.1.0.dist-info/METADATA,sha256=iFMpxkdq9BNdpgyc_wOjjXLNHP_O5sWtTlo1oxyB3fE,6797
+pdf_form_proof-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pdf_form_proof-0.1.0.dist-info/entry_points.txt,sha256=zjjAIheRLuJHvRmUHfetpLpSuaYdCU4SL9o9un9qQrg,207
+pdf_form_proof-0.1.0.dist-info/licenses/LICENSE,sha256=DigQ3iN0PR99HtC7Uc_mpZwtOj4-n4ddoYWt0JJiYg8,1073
+pdf_form_proof-0.1.0.dist-info/RECORD,,

pdf_form_proof-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pdf_form_proof-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+pdf-form-fill = pdf_form_proof.cli:fill_main
+pdf-form-inspect = pdf_form_proof.cli:inspect_main
+pdf-form-proof = pdf_form_proof.server:main
+pdf-form-verify = pdf_form_proof.legibility:main

pdf_form_proof-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EssenceAlignment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.