@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/pdf/scripts/pdf_form_layout.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Validate a form-spec layout BEFORE building the PDF, with optional
+visual overlay rendering for review with a vision model.
+
+Input is the same JSON spec pdf_make_form.py consumes: each field has
+"page", "label_box" and "entry_box" as [x0, y0, x1, y1] in PDF points
+(origin bottom-left). Checks per field:
+  - boxes lie within the page bounds
+  - boxes are well-formed (x0 < x1, y0 < y1)
+  - entry boxes meet minimum sizes (default 8x8 pt; 12 pt height for text)
+  - no two entry boxes on the same page overlap
+  - the label sits near its entry box (default within 150 pt gap)
+
+Prints a JSON report {"ok": bool, "fields": [...], "errors": N};
+exit 0 when clean, 1 when any check fails.
+
+--render-overlay OUT.png rasterizes --overlay-page (default 1) of an
+existing PDF (--pdf; a blank page of spec size if omitted) and draws
+label boxes (blue) and entry boxes (red) with field names, for
+review with `vision_analyze`. If no rasterizer (pypdfium2/pdftoppm) is
+available the overlay is skipped with {"rendered": false, "missing": [...]}
+and validation exit status is unchanged.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+MIN_W = 8.0
+MIN_H = 8.0
+MIN_TEXT_H = 12.0
+MAX_LABEL_GAP = 150.0
+
+
+def _boxes_overlap(a, b) -> bool:
+    return not (a[2] <= b[0] or b[2] <= a[0] or a[3] <= b[1] or b[3] <= a[1])
+
+
+def _box_gap(a, b) -> float:
+    dx = max(b[0] - a[2], a[0] - b[2], 0.0)
+    dy = max(b[1] - a[3], a[1] - b[3], 0.0)
+    return (dx ** 2 + dy ** 2) ** 0.5
+
+
+def _page_size(spec: dict) -> tuple[float, float]:
+    sizes = {"a4": (595.27, 841.89), "letter": (612.0, 792.0)}
+    ps = spec.get("page_size", "A4")
+    if isinstance(ps, (list, tuple)) and len(ps) == 2:
+        return float(ps[0]), float(ps[1])
+    return sizes.get(str(ps).lower(), sizes["a4"])
+
+
+def _check_box(box, width, height, min_w, min_h, kind) -> list[str]:
+    problems = []
+    if box is None:
+        return [f"{kind}_box missing"]
+    x0, y0, x1, y1 = (float(v) for v in box)
+    if x0 >= x1 or y0 >= y1:
+        problems.append(f"{kind}_box malformed (need x0<x1 and y0<y1): {box}")
+        return problems
+    if x0 < 0 or y0 < 0 or x1 > width or y1 > height:
+        problems.append(f"{kind}_box outside page bounds {width}x{height}: {box}")
+    if x1 - x0 < min_w or y1 - y0 < min_h:
+        problems.append(f"{kind}_box below minimum size {min_w}x{min_h}: {box}")
+    return problems
+
+
+def validate(spec: dict) -> dict:
+    width, height = _page_size(spec)
+    fields = spec.get("fields", [])
+    report = []
+    entry_boxes: dict[int, list[tuple[str, list[float]]]] = {}
+    for f in fields:
+        name = f.get("name", "?")
+        page = int(f.get("page", 1))
+        problems = []
+        min_h = MIN_TEXT_H if f.get("type", "text") in ("text", "dropdown") else MIN_H
+        entry = f.get("entry_box")
+        problems += _check_box(entry, width, height, MIN_W, min_h, "entry")
+        label = f.get("label_box")
+        if f.get("label"):
+            problems += _check_box(label, width, height, 4, 4, "label")
+            if entry and label and len(problems) == 0:
+                gap = _box_gap([float(v) for v in label], [float(v) for v in entry])
+                if gap > MAX_LABEL_GAP:
+                    problems.append(f"label is {gap:.0f}pt from its entry box (max {MAX_LABEL_GAP:.0f})")
+                if _boxes_overlap([float(v) for v in label], [float(v) for v in entry]):
+                    problems.append("label_box overlaps its own entry_box")
+        if entry and not any("malformed" in p or "missing" in p for p in problems):
+            ebox = [float(v) for v in entry]
+            for other_name, other_box in entry_boxes.get(page, []):
+                if _boxes_overlap(ebox, other_box):
+                    problems.append(f"entry_box overlaps field {other_name!r}")
+            entry_boxes.setdefault(page, []).append((name, ebox))
+        report.append({"name": name, "page": page, "ok": not problems, "problems": problems})
+    errors = sum(1 for r in report if not r["ok"])
+    return {"ok": errors == 0, "page_size": [width, height],
+            "field_count": len(report), "errors": errors, "fields": report}
+
+
+def render_overlay(spec: dict, pdf_path: str | None, page: int, out_png: str,
+                   dpi: int = 100) -> dict:
+    sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent))
+    import _raster
+    if not _raster.available_backends() and pdf_path:
+        return {"rendered": False, "missing": _raster.missing_hints()}
+    from PIL import Image, ImageDraw
+    width, height = _page_size(spec)
+    if pdf_path:
+        img = _raster.rasterize_page(pdf_path, page, dpi=dpi)
+        if img is None:
+            return {"rendered": False, "missing": _raster.missing_hints()}
+        scale = img.width / width
+    else:
+        scale = dpi / 72.0
+        img = Image.new("RGB", (int(width * scale), int(height * scale)), "white")
+    draw = ImageDraw.Draw(img)
+
+    def to_px(box):
+        x0, y0, x1, y1 = (float(v) for v in box)
+        return [x0 * scale, img.height - y1 * scale, x1 * scale, img.height - y0 * scale]
+
+    for f in spec.get("fields", []):
+        if int(f.get("page", 1)) != page:
+            continue
+        if f.get("entry_box"):
+            px = to_px(f["entry_box"])
+            draw.rectangle(px, outline=(220, 30, 30), width=2)
+            draw.text((px[0] + 2, px[1] + 2), str(f.get("name", "?")), fill=(220, 30, 30))
+        if f.get("label_box"):
+            draw.rectangle(to_px(f["label_box"]), outline=(30, 60, 220), width=2)
+    img.save(out_png)
+    return {"rendered": True, "overlay": out_png, "page": page,
+            "legend": {"entry_box": "red", "label_box": "blue"}}
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(
+        description="Validate form-spec layout (boxes, overlaps, label pairing); "
+                    "optionally render an annotated overlay image.")
+    parser.add_argument("spec", help="Form spec JSON (same format as pdf_make_form.py)")
+    parser.add_argument("--pdf", help="Existing PDF to rasterize under the overlay "
+                                      "(blank page if omitted)")
+    parser.add_argument("--render-overlay", metavar="OUT_PNG",
+                        help="Write an annotated PNG for visual review")
+    parser.add_argument("--overlay-page", type=int, default=1, help="1-based page (default 1)")
+    parser.add_argument("--dpi", type=int, default=100, help="Overlay render DPI (default 100)")
+    args = parser.parse_args()
+
+    with open(args.spec, encoding="utf-8") as fh:
+        spec = json.load(fh)
+    result = validate(spec)
+    if args.render_overlay:
+        result["overlay"] = render_overlay(spec, args.pdf, args.overlay_page,
+                                           args.render_overlay, args.dpi)
+    json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+    print()
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pdf/scripts/pdf_make_form.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Create a fillable AcroForm PDF from a JSON spec (reportlab canvas.acroForm).
+
+Spec format (UTF-8 JSON; coordinates in PDF points, origin bottom-left):
+{
+  "title": "Example Intake Form",
+  "page_size": "A4",                  // or "letter" or [width, height]
+  "page_count": 1,
+  "fields": [
+    {"name": "surname", "type": "text", "page": 1,
+     "label": "Surname", "label_box": [72, 700, 150, 714],
+     "entry_box": [160, 696, 400, 716], "value": "", "tooltip": "Family name"},
+    {"name": "agree", "type": "checkbox", "page": 1,
+     "label": "I agree", "label_box": [72, 660, 150, 674],
+     "entry_box": [160, 658, 176, 674], "checked": false},
+    {"name": "color", "type": "radio", "page": 1,
+     "label": "Color", "label_box": [72, 620, 150, 634],
+     "entry_box": [160, 616, 400, 636], "options": ["red", "blue"],
+     "value": "red"},
+    {"name": "size", "type": "dropdown", "page": 1,
+     "label": "Size", "label_box": [72, 580, 150, 594],
+     "entry_box": [160, 576, 300, 596], "options": ["small", "large"],
+     "value": "small"}
+  ]
+}
+The same spec (label_box/entry_box/page) is what pdf_form_layout.py validates,
+so lint the layout first, then build.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _reconfigure_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+
+def _page_size(spec: dict):
+    from reportlab.lib.pagesizes import A4, letter
+    ps = spec.get("page_size", "A4")
+    if isinstance(ps, (list, tuple)) and len(ps) == 2:
+        return float(ps[0]), float(ps[1])
+    return letter if str(ps).lower() == "letter" else A4
+
+
+def build_form(spec: dict, out_path: str) -> int:
+    try:
+        from reportlab.lib import colors
+        from reportlab.pdfgen import canvas
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install reportlab'", file=sys.stderr)
+        return 2
+
+    width, height = _page_size(spec)
+    page_count = int(spec.get("page_count", 1))
+    fields = spec.get("fields", [])
+    by_page: dict[int, list[dict]] = {}
+    for f in fields:
+        by_page.setdefault(int(f.get("page", 1)), []).append(f)
+    page_count = max([page_count, *by_page.keys()]) if by_page else page_count
+
+    c = canvas.Canvas(out_path, pagesize=(width, height))
+    if spec.get("title"):
+        c.setTitle(str(spec["title"]))
+    if spec.get("author"):
+        c.setAuthor(str(spec["author"]))
+    form = c.acroForm
+    created = []
+
+    for pageno in range(1, page_count + 1):
+        for f in by_page.get(pageno, []):
+            name = f["name"]
+            ftype = f.get("type", "text")
+            ex0, ey0, ex1, ey1 = (float(v) for v in f["entry_box"])
+            ew, eh = ex1 - ex0, ey1 - ey0
+            if f.get("label"):
+                lx, ly = (float(f["label_box"][0]), float(f["label_box"][1])) \
+                    if f.get("label_box") else (ex0 - 90, ey0 + 4)
+                c.setFont("Helvetica", float(f.get("label_size", 10)))
+                c.setFillColor(colors.black)
+                c.drawString(lx, ly + 2, str(f["label"]))
+            tooltip = f.get("tooltip", "")
+            if ftype == "text":
+                form.textfield(name=name, x=ex0, y=ey0, width=ew, height=eh,
+                               value=str(f.get("value", "")), tooltip=tooltip,
+                               borderWidth=0.5, forceBorder=True)
+            elif ftype == "checkbox":
+                size = min(ew, eh)
+                form.checkbox(name=name, x=ex0, y=ey0, size=size,
+                              checked=bool(f.get("checked", False)),
+                              buttonStyle="check", tooltip=tooltip,
+                              borderWidth=0.5, forceBorder=True)
+            elif ftype == "radio":
+                options = f.get("options", [])
+                if not options:
+                    print(f"Warning: radio {name!r} has no options, skipped", file=sys.stderr)
+                    continue
+                size = min(eh, ew / max(len(options), 1) * 0.5, 16)
+                slot = ew / len(options)
+                sel = f.get("value")
+                c.setFont("Helvetica", 8)
+                for i, opt in enumerate(options):
+                    ox = ex0 + i * slot
+                    form.radio(name=name, value=str(opt), x=ox, y=ey0, size=size,
+                               selected=(str(opt) == str(sel)), buttonStyle="circle",
+                               borderWidth=0.5, forceBorder=True)
+                    c.drawString(ox + size + 2, ey0 + size / 3, str(opt))
+            elif ftype == "dropdown":
+                options = [str(o) for o in f.get("options", [])]
+                value = str(f.get("value", options[0] if options else ""))
+                form.choice(name=name, x=ex0, y=ey0, width=ew, height=eh,
+                            options=options, value=value, tooltip=tooltip,
+                            borderWidth=0.5, forceBorder=True)
+            else:
+                print(f"Warning: unknown field type {ftype!r} for {name!r}, skipped",
+                      file=sys.stderr)
+                continue
+            created.append({"name": name, "type": ftype, "page": pageno})
+        c.showPage()
+    c.save()
+    print(json.dumps({"output": out_path, "pages": page_count, "fields": created},
+                     ensure_ascii=False))
+    return 0
+
+
+def main() -> int:
+    _reconfigure_stdio()
+    parser = argparse.ArgumentParser(
+        description="Create a fillable AcroForm PDF from a JSON spec (reportlab).")
+    parser.add_argument("spec", help="Path to UTF-8 JSON form spec")
+    parser.add_argument("-o", "--output", required=True, help="Output PDF path")
+    args = parser.parse_args()
+    with open(args.spec, encoding="utf-8") as fh:
+        spec = json.load(fh)
+    return build_form(spec, args.output)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pdf/scripts/pdf_merge.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Merge multiple PDFs into one, optionally adding a bookmark per source file."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Merge PDFs (pypdf).")
+    parser.add_argument("inputs", nargs="+", help="Input PDF paths, in order")
+    parser.add_argument("-o", "--output", required=True, help="Output PDF path")
+    parser.add_argument("--bookmarks", action="store_true",
+                        help="Add a top-level bookmark per input file (its basename)")
+    args = parser.parse_args()
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+
+    writer = PdfWriter()
+    total = 0
+    for path in args.inputs:
+        reader = PdfReader(path)
+        if reader.is_encrypted:
+            print(f"Error: {path} is encrypted; decrypt it first with pdf_secure.py --decrypt", file=sys.stderr)
+            return 3
+        start = total
+        for page in reader.pages:
+            writer.add_page(page)
+            total += 1
+        if args.bookmarks:
+            writer.add_outline_item(os.path.splitext(os.path.basename(path))[0], start)
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps({"output": args.output, "inputs": len(args.inputs), "page_count": total}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pdf/scripts/pdf_meta.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Document metadata and file attachments for PDFs (pypdf).
+
+Modes (one required):
+  --set-meta            set metadata keys given via --title/--author/...
+  --clear-meta          drop all document info metadata
+  --attach FILE         embed a file attachment
+  --list-attachments    list embedded attachment names
+  --extract-attachments DIR  write all attachments into DIR
+
+Metadata note: values are stored in the classic DocInfo dictionary
+(Title/Author/Subject/Keywords). XMP metadata, if present, is not
+rewritten and may disagree in sophisticated viewers.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Set/clear PDF metadata; manage attachments.")
+    parser.add_argument("pdf", help="Input PDF path")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--set-meta", action="store_true", help="Set metadata fields")
+    mode.add_argument("--clear-meta", action="store_true", help="Remove all DocInfo metadata")
+    mode.add_argument("--attach", metavar="FILE", help="Embed FILE as an attachment")
+    mode.add_argument("--list-attachments", action="store_true", help="List attachment names")
+    mode.add_argument("--extract-attachments", metavar="DIR", help="Extract attachments into DIR")
+    parser.add_argument("-o", "--output", help="Output PDF (required for write modes)")
+    parser.add_argument("--title")
+    parser.add_argument("--author")
+    parser.add_argument("--subject")
+    parser.add_argument("--keywords")
+    parser.add_argument("--password", help="Password if the input is encrypted")
+    args = parser.parse_args()
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+
+    reader = PdfReader(args.pdf)
+    if reader.is_encrypted:
+        if args.password is None or not reader.decrypt(args.password):
+            print("Error: input is encrypted; pass --password", file=sys.stderr)
+            return 3
+
+    if args.list_attachments:
+        names = list(reader.attachments.keys())
+        json.dump({"attachment_count": len(names), "attachments": names}, sys.stdout,
+                  ensure_ascii=False, indent=2)
+        print()
+        return 0
+
+    if args.extract_attachments:
+        out_dir = Path(args.extract_attachments)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        written = []
+        for name, contents in reader.attachments.items():
+            data = contents[0] if isinstance(contents, list) else contents
+            safe = os.path.basename(name) or "attachment.bin"
+            target = out_dir / safe
+            with open(target, "wb") as fh:
+                fh.write(bytes(data))
+            written.append(str(target))
+        json.dump({"extracted": written}, sys.stdout, ensure_ascii=False, indent=2)
+        print()
+        return 0
+
+    if not args.output:
+        print("Error: -o/--output is required for write modes", file=sys.stderr)
+        return 4
+
+    writer = PdfWriter()
+    writer.append(reader)
+
+    if args.set_meta:
+        meta = {}
+        for key, value in ((f"/{k.capitalize()}", getattr(args, k))
+                           for k in ("title", "author", "subject", "keywords")):
+            if value is not None:
+                meta[key] = value
+        if not meta:
+            print("Error: --set-meta needs at least one of --title/--author/--subject/--keywords",
+                  file=sys.stderr)
+            return 4
+        writer.add_metadata(meta)
+        result = {"output": args.output, "set": {k.lstrip("/"): v for k, v in meta.items()}}
+    elif args.clear_meta:
+        writer.metadata = None
+        result = {"output": args.output, "cleared": True}
+    else:  # --attach
+        attach_path = Path(args.attach)
+        with open(attach_path, "rb") as fh:
+            writer.add_attachment(attach_path.name, fh.read())
+        result = {"output": args.output, "attached": attach_path.name}
+
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pdf/scripts/pdf_page_image.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Export PDF pages as PNG images at a chosen DPI.
+
+Rasterizer fallback chain: pypdfium2 (pip) -> pdftoppm (poppler-utils).
+When neither is available, exits 0 with {"rendered": false, "missing": [...]}
+so callers can branch instead of crashing.
+
+Typical uses: visual verification with a vision model, and exporting
+image-only (scanned) pages for hand-off to the references/ocr-extraction.md in this skill.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def parse_pages(spec: str, page_count: int) -> list[int]:
+    """'1-3,5,9-' (1-based, inclusive) -> sorted page list."""
+    pages: set[int] = set()
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            start_s, _, end_s = part.partition("-")
+            start = int(start_s) if start_s else 1
+            end = int(end_s) if end_s else page_count
+            pages.update(range(start, end + 1))
+        else:
+            pages.add(int(part))
+    bad = [p for p in pages if not 1 <= p <= page_count]
+    if bad:
+        raise ValueError(f"pages out of range 1-{page_count}: {sorted(bad)}")
+    return sorted(pages)
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Export PDF pages as PNG images.")
+    parser.add_argument("pdf", help="Input PDF path")
+    parser.add_argument("--pages", default="1-", help="1-based ranges, e.g. '1-3,5' (default: all)")
+    parser.add_argument("--dpi", type=int, default=150, help="Render DPI (default 150)")
+    parser.add_argument("--out-dir", required=True, help="Directory for PNG files")
+    parser.add_argument("--prefix", default="page", help="Output filename prefix (default 'page')")
+    parser.add_argument("--password", help="Password for encrypted PDFs")
+    args = parser.parse_args()
+
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    import _raster
+
+    if not _raster.available_backends():
+        json.dump({"rendered": False, "missing": _raster.missing_hints()}, sys.stdout)
+        print()
+        return 0
+
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+    reader = PdfReader(args.pdf)
+    if reader.is_encrypted:
+        if args.password is None or not reader.decrypt(args.password):
+            print("File is encrypted; pass --password.", file=sys.stderr)
+            return 3
+    page_count = len(reader.pages)
+
+    try:
+        pages = parse_pages(args.pages, page_count)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 4
+
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    files = []
+    for pageno in pages:
+        img = _raster.rasterize_page(args.pdf, pageno, dpi=args.dpi, password=args.password)
+        if img is None:
+            json.dump({"rendered": False, "missing": _raster.missing_hints()}, sys.stdout)
+            print()
+            return 0
+        out_path = out_dir / f"{args.prefix}{pageno:03d}.png"
+        img.save(out_path)
+        files.append(str(out_path))
+    json.dump({"rendered": True, "dpi": args.dpi, "page_count": page_count,
+               "files": files}, sys.stdout, ensure_ascii=False, indent=2)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())