@panda-agent/panda-cli 0.1.28 → 0.1.30

package/skills/pdf/scripts/check_bounding_boxes.py

@@ -0,0 +1,198 @@
+"""Validate geometric constraints of form field bounding regions.
+
+Detects overlapping bounding boxes and entry regions too small for their
+specified font size.
+
+Usage:
+    python check_bounding_boxes.py <fields.json>
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, TextIO, Tuple
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+MAX_REPORTED_ISSUES: int = 20
+
+BoundingBox = Tuple[float, float, float, float]
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+
+class FieldRegion:
+    """Encapsulates a rectangle associated with a specific form field."""
+
+    __slots__ = ("bounds", "kind", "parent_field")
+
+    def __init__(
+        self,
+        bounds: List[float],
+        kind: str,
+        parent_field: Dict[str, Any],
+    ) -> None:
+        self.bounds = bounds
+        self.kind = kind
+        self.parent_field = parent_field
+
+
+# ---------------------------------------------------------------------------
+# Geometry helpers
+# ---------------------------------------------------------------------------
+
+
+def _do_overlap(box_a: List[float], box_b: List[float]) -> bool:
+    """Determine whether two axis-aligned rectangles share any area."""
+    separated_x: bool = box_a[0] >= box_b[2] or box_b[0] >= box_a[2]
+    separated_y: bool = box_a[1] >= box_b[3] or box_b[1] >= box_a[3]
+    return not separated_x and not separated_y
+
+
+def _height_too_small(region: FieldRegion) -> bool:
+    """Check if an entry region is vertically insufficient for its text."""
+    if "entry_text" not in region.parent_field:
+        return False
+    font_size: float = region.parent_field["entry_text"].get("font_size", 14)
+    height: float = region.bounds[3] - region.bounds[1]
+    return height < font_size
+
+
+# ---------------------------------------------------------------------------
+# Core validation
+# ---------------------------------------------------------------------------
+
+
+def validate_field_geometry(input_stream: TextIO) -> List[str]:
+    """Analyze all field bounding boxes from the given JSON stream.
+
+    Returns a list of diagnostic strings.
+    """
+    doc: Dict[str, Any] = json.load(input_stream)
+    form_entries: List[Dict[str, Any]] = doc["form_fields"]
+    diagnostics: List[str] = ["Read %d fields" % len(form_entries)]
+
+    # Build flat list of all regions
+    all_regions: List[FieldRegion] = []
+    for entry in form_entries:
+        all_regions.append(
+            FieldRegion(entry["label_bounding_box"], "label", entry)
+        )
+        all_regions.append(
+            FieldRegion(entry["entry_bounding_box"], "entry", entry)
+        )
+
+    found_problem: bool = False
+    idx: int = 0
+
+    while idx < len(all_regions):
+        ri = all_regions[idx]
+
+        # Check pairwise overlaps with subsequent regions
+        for jdx in range(idx + 1, len(all_regions)):
+            rj = all_regions[jdx]
+            if ri.parent_field["page_number"] != rj.parent_field["page_number"]:
+                continue
+            if not _do_overlap(ri.bounds, rj.bounds):
+                continue
+
+            found_problem = True
+            if ri.parent_field is rj.parent_field:
+                msg = (
+                    "FAILURE: intersection between label and entry "
+                    "bounding boxes for `{}` ({}, {})".format(
+                        ri.parent_field["description"], ri.bounds, rj.bounds
+                    )
+                )
+            else:
+                msg = (
+                    "FAILURE: intersection between {} bounding box for "
+                    "`{}` ({}) and {} bounding box for `{}` ({})".format(
+                        ri.kind,
+                        ri.parent_field["description"],
+                        ri.bounds,
+                        rj.kind,
+                        rj.parent_field["description"],
+                        rj.bounds,
+                    )
+                )
+            diagnostics.append(msg)
+            if len(diagnostics) >= MAX_REPORTED_ISSUES:
+                diagnostics.append(
+                    "Aborting further checks; fix bounding boxes and try again"
+                )
+                return diagnostics
+
+        # Height validation for entry regions
+        if ri.kind == "entry" and _height_too_small(ri):
+            found_problem = True
+            height: float = ri.bounds[3] - ri.bounds[1]
+            font_size = ri.parent_field["entry_text"].get("font_size", 14)
+            diagnostics.append(
+                "FAILURE: entry bounding box height ({}) for `{}` is too short "
+                "for the text content (font size: {}). Increase the box height "
+                "or decrease the font size.".format(
+                    height, ri.parent_field["description"], font_size
+                )
+            )
+            if len(diagnostics) >= MAX_REPORTED_ISSUES:
+                diagnostics.append(
+                    "Aborting further checks; fix bounding boxes and try again"
+                )
+                return diagnostics
+
+        idx += 1
+
+    if not found_problem:
+        diagnostics.append("SUCCESS: All bounding boxes are valid")
+    return diagnostics
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Validate bounding box geometry in a fields.json specification. "
+            "Detects overlaps and insufficient entry heights."
+        )
+    )
+    parser.add_argument(
+        "fields_json",
+        type=Path,
+        help="Path to the fields.json file to validate.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments and run geometry validation."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    fields_json: Path = args.fields_json
+    if not fields_json.exists():
+        print("ERROR: File not found: {}".format(fields_json), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    with open(fields_json, "r", encoding="utf-8") as handle:
+        results = validate_field_geometry(handle)
+
+    for line in results:
+        print(line)
+
+
+if __name__ == "__main__":
+    main()

package/skills/pdf/scripts/check_fillable_fields.py

@@ -0,0 +1,64 @@
+"""Detect whether a PDF document contains interactive form fields.
+
+Usage:
+    python check_fillable_fields.py <pdf_path>
+
+Outputs a human-readable message indicating whether the document
+has native fillable form widgets.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+import pypdf
+
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+MSG_HAS_FIELDS: str = "This PDF has fillable form fields"
+MSG_NO_FIELDS: str = (
+    "This PDF does not have fillable form fields; "
+    "you will need to visually determine where to enter data"
+)
+
+
+def check_fillable(pdf_path: Path) -> bool:
+    """Return True if the PDF at *pdf_path* contains interactive form fields."""
+    reader = pypdf.PdfReader(str(pdf_path))
+    return bool(reader.get_fields())
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Detect whether a PDF contains interactive form fields."
+    )
+    parser.add_argument(
+        "pdf_path",
+        type=Path,
+        help="Path to the PDF document to inspect.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments, inspect PDF, print result."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    pdf_path: Path = args.pdf_path
+    if not pdf_path.exists():
+        print("ERROR: File not found: {}".format(pdf_path), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    has_fields = check_fillable(pdf_path)
+    if has_fields:
+        print(MSG_HAS_FIELDS)
+    else:
+        print(MSG_NO_FIELDS)
+
+
+if __name__ == "__main__":
+    main()

package/skills/pdf/scripts/convert_pdf_to_images.py

@@ -0,0 +1,102 @@
+"""Render each page of a PDF document as a PNG image file.
+
+Usage:
+    python convert_pdf_to_images.py <input.pdf> <output_directory>
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List
+
+import pdf2image
+from PIL import Image
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+RENDER_DPI: int = 200
+DEFAULT_MAX_DIMENSION: int = 1000
+
+OUTPUT_FORMAT: str = "png"
+FILENAME_TEMPLATE: str = "page_{}.png"
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+
+def render_pages_to_png(
+    source_pdf: Path,
+    dest_folder: Path,
+    dimension_cap: int = DEFAULT_MAX_DIMENSION,
+) -> None:
+    """Convert all pages in *source_pdf* to PNG files within *dest_folder*."""
+    rendered: List[Image.Image] = pdf2image.convert_from_path(
+        str(source_pdf), dpi=RENDER_DPI
+    )
+
+    for page_idx, img in enumerate(rendered):
+        w, h = img.size
+        needs_resize: bool = w > dimension_cap or h > dimension_cap
+        if needs_resize:
+            ratio: float = min(dimension_cap / w, dimension_cap / h)
+            resized_w: int = int(w * ratio)
+            resized_h: int = int(h * ratio)
+            img = img.resize((resized_w, resized_h))
+
+        out_path: Path = dest_folder / FILENAME_TEMPLATE.format(page_idx + 1)
+        img.save(str(out_path))
+        print(
+            "Saved page %d as %s (size: %s)"
+            % (page_idx + 1, out_path, str(img.size))
+        )
+
+    print("Converted %d pages to PNG images" % len(rendered))
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Render PDF pages as PNG image files."
+    )
+    parser.add_argument(
+        "input_pdf",
+        type=Path,
+        help="Path to the source PDF document.",
+    )
+    parser.add_argument(
+        "output_directory",
+        type=Path,
+        help="Directory to write PNG page images into.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments, create output dir, render pages."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    input_pdf: Path = args.input_pdf
+    output_dir: Path = args.output_directory
+
+    if not input_pdf.exists():
+        print("ERROR: File not found: {}".format(input_pdf), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    render_pages_to_png(input_pdf, output_dir)
+
+
+if __name__ == "__main__":
+    main()

package/skills/pdf/scripts/create_validation_image.py

@@ -0,0 +1,125 @@
+"""Overlay colored rectangles on a page image to visualize field bounding boxes.
+
+Usage:
+    python create_validation_image.py <page_number> <fields.json> <input_image> <output_image>
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+from PIL import Image as PILImage
+from PIL import ImageDraw as PILDraw
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS: int = 0
+EXIT_FAILURE: int = 1
+
+ENTRY_OUTLINE_COLOR: str = "red"
+LABEL_OUTLINE_COLOR: str = "blue"
+OUTLINE_WIDTH: int = 2
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+
+def generate_overlay(
+    target_page: int,
+    fields_path: Path,
+    src_image: Path,
+    dst_image: Path,
+) -> None:
+    """Draw entry (red) and label (blue) rectangles onto the source image
+    for all fields matching *target_page*, then save to *dst_image*.
+    """
+    with open(fields_path, "r", encoding="utf-8") as fh:
+        spec: Dict[str, Any] = json.load(fh)
+
+    canvas = PILImage.open(str(src_image))
+    pen = PILDraw.Draw(canvas)
+    box_count: int = 0
+
+    matching: List[Dict[str, Any]] = [
+        f for f in spec["form_fields"] if f["page_number"] == target_page
+    ]
+    for fld in matching:
+        pen.rectangle(
+            fld["entry_bounding_box"],
+            outline=ENTRY_OUTLINE_COLOR,
+            width=OUTLINE_WIDTH,
+        )
+        pen.rectangle(
+            fld["label_bounding_box"],
+            outline=LABEL_OUTLINE_COLOR,
+            width=OUTLINE_WIDTH,
+        )
+        box_count += 2
+
+    canvas.save(str(dst_image))
+    print(
+        "Created validation image at {} with {} bounding boxes".format(
+            dst_image, box_count
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Visualize field bounding boxes by overlaying colored rectangles on a page image."
+    )
+    parser.add_argument(
+        "page_number",
+        type=int,
+        help="1-indexed page number to visualize.",
+    )
+    parser.add_argument(
+        "fields_json",
+        type=Path,
+        help="Path to the fields.json specification file.",
+    )
+    parser.add_argument(
+        "input_image",
+        type=Path,
+        help="Path to the source page image.",
+    )
+    parser.add_argument(
+        "output_image",
+        type=Path,
+        help="Destination path for the annotated image.",
+    )
+    return parser
+
+
+def main() -> None:
+    """Entry point: parse arguments and generate validation overlay."""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    fields_json: Path = args.fields_json
+    input_image: Path = args.input_image
+
+    if not fields_json.exists():
+        print("ERROR: File not found: {}".format(fields_json), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    if not input_image.exists():
+        print("ERROR: File not found: {}".format(input_image), file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+
+    generate_overlay(args.page_number, fields_json, input_image, args.output_image)
+
+
+if __name__ == "__main__":
+    main()