@panda-agent/panda-cli 0.1.29 → 0.1.30

package/skills/pdf/scripts/extract_form_field_info.py

@@ -0,0 +1,220 @@
+"""Introspect fillable PDF form fields and serialize their metadata to JSON.
+
+Supports text inputs, checkboxes, radio button groups, and dropdown choices.
+
+Usage:
+    python extract_form_field_info.py <input.pdf> <output.json>
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+import pypdf
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+FIELD_TYPE_TEXT: str = "text"
+FIELD_TYPE_CHECKBOX: str = "checkbox"
+FIELD_TYPE_RADIO: str = "radio_group"
+FIELD_TYPE_CHOICE: str = "choice"
+
+PDF_FT_TEXT: str = "/Tx"
+PDF_FT_BUTTON: str = "/Btn"
+PDF_FT_CHOICE: str = "/Ch"
+
+OFF_STATE: str = "/Off"
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_qualified_name(annot_obj: Any) -> Optional[str]:
+    """Walk the /Parent chain to assemble a dot-separated field identifier."""
+    parts: List[str] = []
+    node = annot_obj
+    while node is not None:
+        name_component = node.get("/T")
+        if name_component:
+            parts.append(name_component)
+        node = node.get("/Parent")
+    return ".".join(reversed(parts)) if parts else None
+
+
+def _build_field_descriptor(raw_field: Any, identifier: str) -> Dict[str, Any]:
+    """Construct a typed descriptor dict from a raw PDF field object."""
+    descriptor: Dict[str, Any] = {"field_id": identifier}
+    field_type_code = raw_field.get("/FT")
+
+    if field_type_code == PDF_FT_TEXT:
+        descriptor["type"] = FIELD_TYPE_TEXT
+
+    elif field_type_code == PDF_FT_BUTTON:
+        descriptor["type"] = FIELD_TYPE_CHECKBOX
+        available_states = raw_field.get("/_States_", [])
+        if len(available_states) == 2:
+            off_present = OFF_STATE in available_states
+            if off_present:
+                on_val = (
+                    available_states[0]
+                    if available_states[0] != OFF_STATE
+                    else available_states[1]
+                )
+                descriptor["checked_value"] = on_val
+                descriptor["unchecked_value"] = OFF_STATE
+            else:
+                print(
+                    "Unexpected state values for checkbox `$%s`. "
+                    "Its checked and unchecked values may not be correct; "
+                    "if you're trying to check it, visually verify the results."
+                    % identifier
+                )
+                descriptor["checked_value"] = available_states[0]
+                descriptor["unchecked_value"] = available_states[1]
+
+    elif field_type_code == PDF_FT_CHOICE:
+        descriptor["type"] = FIELD_TYPE_CHOICE
+        available_states = raw_field.get("/_States_", [])
+        descriptor["choice_options"] = [
+            {"value": opt[0], "text": opt[1]} for opt in available_states
+        ]
+
+    else:
+        descriptor["type"] = "unknown (%s)" % field_type_code
+
+    return descriptor
+
+
+def _ordering_key(item: Dict[str, Any]) -> List[Any]:
+    """Produce a sort key: page number, then top-to-bottom left-to-right."""
+    if "radio_options" in item:
+        rect = item["radio_options"][0]["rect"] or [0, 0, 0, 0]
+    else:
+        rect = item.get("rect") or [0, 0, 0, 0]
+    return [item.get("page"), [-rect[1], rect[0]]]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_field_info(pdf_reader: pypdf.PdfReader) -> List[Dict[str, Any]]:
+    """Extract structured field metadata from all form fields in the document.
+
+    Returns a sorted list of field descriptors with page/rect info.
+    """
+    raw_fields = pdf_reader.get_fields()
+    if not raw_fields:
+        return []
+
+    descriptors_map: Dict[str, Dict[str, Any]] = {}
+    candidate_radio_ids: Set[str] = set()
+
+    for fid, fobj in raw_fields.items():
+        if fobj.get("/Kids"):
+            if fobj.get("/FT") == PDF_FT_BUTTON:
+                candidate_radio_ids.add(fid)
+            continue
+        descriptors_map[fid] = _build_field_descriptor(fobj, fid)
+
+    radio_groups: Dict[str, Dict[str, Any]] = {}
+
+    for pg_idx, pg in enumerate(pdf_reader.pages):
+        annot_list = pg.get("/Annots", [])
+        for annot in annot_list:
+            qualified = _resolve_qualified_name(annot)
+            if qualified in descriptors_map:
+                descriptors_map[qualified]["page"] = pg_idx + 1
+                descriptors_map[qualified]["rect"] = annot.get("/Rect")
+            elif qualified in candidate_radio_ids:
+                try:
+                    active_vals = [
+                        k for k in annot["/AP"]["/N"] if k != OFF_STATE
+                    ]
+                except KeyError:
+                    continue
+                if len(active_vals) != 1:
+                    continue
+                rect_val = annot.get("/Rect")
+                if qualified not in radio_groups:
+                    radio_groups[qualified] = {
+                        "field_id": qualified,
+                        "type": FIELD_TYPE_RADIO,
+                        "page": pg_idx + 1,
+                        "radio_options": [],
+                    }
+                radio_groups[qualified]["radio_options"].append({
+                    "value": active_vals[0],
+                    "rect": rect_val,
+                })
+
+    # Filter out fields without a determined page location
+    located = [d for d in descriptors_map.values() if "page" in d]
+    for orphan in descriptors_map.values():
+        if "page" not in orphan:
+            print(
+                "Unable to determine location for field id: %s, ignoring"
+                % orphan.get("field_id")
+            )
+
+    combined = located + list(radio_groups.values())
+    combined.sort(key=_ordering_key)
+    return combined
+
+
+def serialize_field_info(pdf_file: Path, output_json: Path) -> None:
+    """Read the PDF and write field info as JSON."""
+    reader = pypdf.PdfReader(str(pdf_file))
+    info = get_field_info(reader)
+    with open(output_json, "w", encoding="utf-8") as fp:
+        json.dump(info, fp, indent=2)
+    print("Wrote %d fields to %s" % (len(info), output_json))
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Extract fillable form field metadata from a PDF to JSON."
+    )
+    parser.add_argument(
+        "input_pdf",
+        type=Path,
+        help="Path to the source PDF with form fields.",
+    )
+    parser.add_argument(
+        "output_json",
+        type=Path,
+        help="Destination path for the JSON output.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments and run extraction."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    input_pdf: Path = args.input_pdf
+    if not input_pdf.exists():
+        print("ERROR: File not found: {}".format(input_pdf), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    serialize_field_info(input_pdf, args.output_json)
+
+
+if __name__ == "__main__":
+    main()

package/skills/pdf/scripts/extract_form_structure.py

@@ -0,0 +1,202 @@
+"""Analyze non-fillable PDF layout to discover text elements, ruling lines,
+and checkbox-like rectangles.
+
+Produces a JSON manifest for downstream coordinate-based form filling.
+
+Usage:
+    python extract_form_structure.py <input.pdf> <output.json>
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+import pdfplumber
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+# Constraints for identifying checkbox-shaped rectangles
+CHECKBOX_MIN_SIZE: float = 5.0
+CHECKBOX_MAX_SIZE: float = 15.0
+CHECKBOX_ASPECT_TOLERANCE: float = 2.0
+
+# Minimum fraction of page width for a line to be considered "spanning"
+SPANNING_LINE_RATIO: float = 0.5
+
+COORDINATE_PRECISION: int = 1
+
+# ---------------------------------------------------------------------------
+# Geometry helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_checkbox_rect(rect_obj: Dict[str, Any]) -> bool:
+    """Return True if the rectangle resembles a checkbox (small, roughly square)."""
+    w: float = float(rect_obj["x1"]) - float(rect_obj["x0"])
+    h: float = float(rect_obj["bottom"]) - float(rect_obj["top"])
+    size_ok = (
+        CHECKBOX_MIN_SIZE <= w <= CHECKBOX_MAX_SIZE
+        and CHECKBOX_MIN_SIZE <= h <= CHECKBOX_MAX_SIZE
+    )
+    square_ok = abs(w - h) < CHECKBOX_ASPECT_TOLERANCE
+    return size_ok and square_ok
+
+
+def _is_spanning_line(line_obj: Dict[str, Any], page_width: float) -> bool:
+    """Return True if the line covers more than half the page width."""
+    span: float = abs(float(line_obj["x1"]) - float(line_obj["x0"]))
+    return span > page_width * SPANNING_LINE_RATIO
+
+
+# ---------------------------------------------------------------------------
+# Core analysis
+# ---------------------------------------------------------------------------
+
+
+def analyze_pdf_layout(pdf_path: Path) -> Dict[str, Any]:
+    """Open a PDF and extract structural elements.
+
+    Extracts words, long horizontal lines, and small square rectangles
+    (checkboxes). Returns a dict of categorized data.
+    """
+    result: Dict[str, Any] = {
+        "pages": [],
+        "labels": [],
+        "lines": [],
+        "checkboxes": [],
+        "row_boundaries": [],
+    }
+
+    with pdfplumber.open(str(pdf_path)) as doc:
+        for pg_num, pg in enumerate(doc.pages, start=1):
+            result["pages"].append({
+                "page_number": pg_num,
+                "width": float(pg.width),
+                "height": float(pg.height),
+            })
+
+            # Collect word-level text elements
+            for word in pg.extract_words():
+                result["labels"].append({
+                    "page": pg_num,
+                    "text": word["text"],
+                    "x0": round(float(word["x0"]), COORDINATE_PRECISION),
+                    "top": round(float(word["top"]), COORDINATE_PRECISION),
+                    "x1": round(float(word["x1"]), COORDINATE_PRECISION),
+                    "bottom": round(float(word["bottom"]), COORDINATE_PRECISION),
+                })
+
+            # Collect long horizontal rules
+            for ln in pg.lines:
+                if _is_spanning_line(ln, pg.width):
+                    result["lines"].append({
+                        "page": pg_num,
+                        "y": round(float(ln["top"]), COORDINATE_PRECISION),
+                        "x0": round(float(ln["x0"]), COORDINATE_PRECISION),
+                        "x1": round(float(ln["x1"]), COORDINATE_PRECISION),
+                    })
+
+            # Collect checkbox-like rectangles
+            for rect in pg.rects:
+                if _is_checkbox_rect(rect):
+                    x0v: float = float(rect["x0"])
+                    x1v: float = float(rect["x1"])
+                    topv: float = float(rect["top"])
+                    botv: float = float(rect["bottom"])
+                    result["checkboxes"].append({
+                        "page": pg_num,
+                        "x0": round(x0v, COORDINATE_PRECISION),
+                        "top": round(topv, COORDINATE_PRECISION),
+                        "x1": round(x1v, COORDINATE_PRECISION),
+                        "bottom": round(botv, COORDINATE_PRECISION),
+                        "center_x": round((x0v + x1v) / 2, COORDINATE_PRECISION),
+                        "center_y": round((topv + botv) / 2, COORDINATE_PRECISION),
+                    })
+
+    # Derive row boundaries from horizontal lines
+    _compute_row_boundaries(result)
+
+    return result
+
+
+def _compute_row_boundaries(result: Dict[str, Any]) -> None:
+    """Derive row boundary intervals from collected horizontal lines."""
+    per_page_ys: Dict[int, List[float]] = {}
+    for ln in result["lines"]:
+        per_page_ys.setdefault(ln["page"], []).append(ln["y"])
+
+    for pg_key, ys in per_page_ys.items():
+        sorted_ys = sorted(set(ys))
+        for k in range(len(sorted_ys) - 1):
+            result["row_boundaries"].append({
+                "page": pg_key,
+                "row_top": sorted_ys[k],
+                "row_bottom": sorted_ys[k + 1],
+                "row_height": round(
+                    sorted_ys[k + 1] - sorted_ys[k], COORDINATE_PRECISION
+                ),
+            })
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Analyze PDF layout structure: text labels, ruling lines, "
+            "and checkbox shapes."
+        )
+    )
+    parser.add_argument(
+        "input_pdf",
+        type=Path,
+        help="Path to the source PDF to analyze.",
+    )
+    parser.add_argument(
+        "output_json",
+        type=Path,
+        help="Destination path for the JSON structure output.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments and run layout analysis."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    input_pdf: Path = args.input_pdf
+    output_json: Path = args.output_json
+
+    if not input_pdf.exists():
+        print("ERROR: File not found: {}".format(input_pdf), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    print("Extracting structure from %s..." % input_pdf)
+    data = analyze_pdf_layout(input_pdf)
+
+    with open(output_json, "w", encoding="utf-8") as out:
+        json.dump(data, out, indent=2)
+
+    print("Found:")
+    print("  - %d pages" % len(data["pages"]))
+    print("  - %d text labels" % len(data["labels"]))
+    print("  - %d horizontal lines" % len(data["lines"]))
+    print("  - %d checkboxes" % len(data["checkboxes"]))
+    print("  - %d row boundaries" % len(data["row_boundaries"]))
+    print("Saved to %s" % output_json)
+
+
+if __name__ == "__main__":
+    main()

package/skills/pdf/scripts/fill_fillable_fields.py

@@ -0,0 +1,205 @@
+"""Populate interactive PDF form fields with values specified in a JSON manifest.
+
+Validates field IDs, page numbers, and value constraints before writing.
+
+Usage:
+    python fill_fillable_fields.py <input.pdf> <field_values.json> <output.pdf>
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import pypdf
+
+from extract_form_field_info import get_field_info
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def _check_value_constraint(descriptor: Dict[str, Any], val: str) -> Optional[str]:
+    """Verify that *val* is acceptable for the given field descriptor.
+
+    Returns an error string or None if valid.
+    """
+    ftype: str = descriptor["type"]
+    fid: str = descriptor["field_id"]
+
+    if ftype == "checkbox":
+        on_val: str = descriptor["checked_value"]
+        off_val: str = descriptor["unchecked_value"]
+        if val != on_val and val != off_val:
+            return (
+                'ERROR: Invalid value "%s" for checkbox field "%s". '
+                'The checked value is "%s" and the unchecked value is "%s"'
+                % (val, fid, on_val, off_val)
+            )
+
+    elif ftype == "radio_group":
+        allowed: List[str] = [o["value"] for o in descriptor["radio_options"]]
+        if val not in allowed:
+            return (
+                'ERROR: Invalid value "%s" for radio group field "%s". '
+                "Valid values are: %s" % (val, fid, allowed)
+            )
+
+    elif ftype == "choice":
+        allowed = [o["value"] for o in descriptor["choice_options"]]
+        if val not in allowed:
+            return (
+                'ERROR: Invalid value "%s" for choice field "%s". '
+                "Valid values are: %s" % (val, fid, allowed)
+            )
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# pypdf compatibility patch
+# ---------------------------------------------------------------------------
+
+
+def _apply_pypdf_option_patch() -> None:
+    """Monkey-patch pypdf to handle two-element option arrays correctly.
+
+    Some PDFs encode choices as [[export_value, display_text], ...].
+    """
+    from pypdf.generic import DictionaryObject
+    from pypdf.constants import FieldDictionaryAttributes
+
+    _orig = DictionaryObject.get_inherited
+
+    def _patched(self: Any, key: str, default: Any = None) -> Any:
+        out = _orig(self, key, default)
+        if key == FieldDictionaryAttributes.Opt:
+            if isinstance(out, list) and all(
+                isinstance(v, list) and len(v) == 2 for v in out
+            ):
+                out = [pair[0] for pair in out]
+        return out
+
+    DictionaryObject.get_inherited = _patched
+
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+
+def populate_fields(src_pdf: Path, values_json: Path, dest_pdf: Path) -> None:
+    """Read field values from *values_json*, validate against the PDF's actual
+    fields, then write the filled output to *dest_pdf*.
+    """
+    with open(values_json, "r", encoding="utf-8") as fh:
+        requested: List[Dict[str, Any]] = json.load(fh)
+
+    # Group values by page
+    page_map: Dict[int, Dict[str, str]] = {}
+    for item in requested:
+        if "value" not in item:
+            continue
+        page_map.setdefault(item["page"], {})[item["field_id"]] = item["value"]
+
+    reader = pypdf.PdfReader(str(src_pdf))
+
+    # Validate all entries
+    known_fields = get_field_info(reader)
+    lookup: Dict[str, Dict[str, Any]] = {f["field_id"]: f for f in known_fields}
+    error_found: bool = False
+
+    for item in requested:
+        fid: str = item["field_id"]
+        existing = lookup.get(fid)
+        if existing is None:
+            error_found = True
+            print("ERROR: `%s` is not a valid field ID" % fid)
+        elif item["page"] != existing["page"]:
+            error_found = True
+            print(
+                "ERROR: Incorrect page number for `%s` (got %s, expected %s)"
+                % (fid, item["page"], existing["page"])
+            )
+        elif "value" in item:
+            err = _check_value_constraint(existing, item["value"])
+            if err:
+                print(err)
+                error_found = True
+
+    if error_found:
+        sys.exit(EXIT_FAILURE)
+
+    # Write filled PDF
+    writer = pypdf.PdfWriter(clone_from=reader)
+    for pg_num, vals in page_map.items():
+        writer.update_page_form_field_values(
+            writer.pages[pg_num - 1], vals, auto_regenerate=False
+        )
+
+    writer.set_need_appearances_writer(True)
+
+    with open(dest_pdf, "wb") as out:
+        writer.write(out)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Fill interactive PDF form fields using a JSON value manifest."
+    )
+    parser.add_argument(
+        "input_pdf",
+        type=Path,
+        help="Path to the source PDF with form fields.",
+    )
+    parser.add_argument(
+        "field_values_json",
+        type=Path,
+        help="JSON file specifying field IDs and values.",
+    )
+    parser.add_argument(
+        "output_pdf",
+        type=Path,
+        help="Destination path for the filled PDF.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments, apply patch, populate fields."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    input_pdf: Path = args.input_pdf
+    values_json: Path = args.field_values_json
+    output_pdf: Path = args.output_pdf
+
+    if not input_pdf.exists():
+        print("ERROR: File not found: {}".format(input_pdf), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    if not values_json.exists():
+        print("ERROR: File not found: {}".format(values_json), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    _apply_pypdf_option_patch()
+    populate_fields(input_pdf, values_json, output_pdf)
+
+
+if __name__ == "__main__":
+    main()