qubicl-cli 0.1.0-dev.0 → 0.1.0

package/dist/assets/computer/skills/core/pdf/references/forms.md

@@ -0,0 +1,100 @@
+# Building Fillable Forms: spec format and workflow
+
+The same JSON spec drives both `pdf_form_layout.py` (design lint) and
+`pdf_make_form.py` (AcroForm build). Coordinates are PDF points, origin
+at the bottom-left of the page (1 pt = 1/72 inch; A4 is 595.27 x 841.89,
+letter is 612 x 792).
+
+## Spec shape
+
+```json
+{
+  "title": "Example Intake Form",
+  "author": "example-author",
+  "page_size": "A4",
+  "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": "blue"},
+
+    {"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"}
+  ]
+}
+```
+
+- `page_size`: `"A4"`, `"letter"`, or `[width, height]` in points.
+- `page_count`: optional; extended automatically to the highest field page.
+- Boxes are `[x0, y0, x1, y1]` with `x0 < x1`, `y0 < y1`.
+- `label` is drawn as static text near `label_box`; omit it (and
+  `label_box`) for unlabeled fields.
+- `radio`: the buttons are laid out left-to-right inside `entry_box`,
+  one slot per option, each with a small static caption. `value`
+  pre-selects an option by its export name.
+- `dropdown` maps to an AcroForm choice (combo) field.
+
+## Field types → what pdf_read.py --fields reports
+
+| Spec type | /FT | value format after fill |
+|---|---|---|
+| text | /Tx (`text`) | the string |
+| checkbox | /Btn (`button`) | `/Yes` or `/Off` |
+| radio | /Btn (`button`) | `/<export>`, e.g. `/red` |
+| dropdown | /Ch (`choice`) | the option string |
+
+When filling with `pdf_fill_form.py`, checkboxes accept `true`/`false`;
+radio values need the leading slash (`"/red"`); dropdown values are the
+plain option string.
+
+## Layout lint rules (pdf_form_layout.py)
+
+Per field, on its declared page:
+
+- boxes must be well-formed and inside the page bounds;
+- entry boxes must be at least 8x8 pt (12 pt tall for text/dropdown);
+- no two entry boxes on the same page may overlap (the second and later
+  fields of an overlapping cluster are flagged);
+- a label must sit within 150 pt of its entry box and must not overlap it.
+
+Exit code 0 = clean, 1 = at least one problem; the JSON report lists
+per-field `problems`. Lint the spec BEFORE building — fixing numbers in
+JSON is cheaper than debugging a rendered PDF.
+
+## Visual review loop
+
+```bash
+python3 scripts/pdf_form_layout.py spec.json --render-overlay overlay.png [--pdf built.pdf]
+```
+
+Red rectangles = entry boxes (with field names), blue = label boxes.
+Without `--pdf` the overlay is drawn on a blank page (PIL-only, always
+works); with `--pdf` the real page is rasterized underneath
+(needs pypdfium2 or pdftoppm — otherwise the report says
+`"rendered": false` with capability guidance). Inspect the PNG with the
+available Qubicl image or desktop tooling
+and ask specifically about collisions, alignment, and stray labels.
+
+## Radio-group quirks (reportlab + pypdf)
+
+- reportlab requires at least two `radio()` calls per group; a
+  single-option radio group produces a broken field.
+- Pre-selecting is done at build time via `"value"`; changing selection
+  later via `pdf_fill_form.py` needs the slashed export name (`"/red"`).
+- Some viewers render reportlab radio appearances inconsistently after a
+  pypdf fill; verify with `--fields` (data truth) plus a rendered page
+  image (visual truth) rather than either alone.
+- Flattening radio groups is the least reliable flatten case — check the
+  output image before shipping.

package/dist/assets/computer/skills/core/pdf/scripts/_raster.py

@@ -0,0 +1,76 @@
+"""Shared page rasterizer with a fallback chain: pypdfium2 -> pdftoppm.
+
+Returns PIL Images so callers can annotate/save. Not a CLI.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def available_backends() -> list[str]:
+    """Names of usable rasterizer backends, in preference order."""
+    backends = []
+    try:
+        import pypdfium2  # noqa: F401
+        backends.append("pypdfium2")
+    except ImportError:
+        pass
+    if shutil.which("pdftoppm"):
+        backends.append("pdftoppm")
+    return backends
+
+
+def missing_hints() -> list[str]:
+    """Qubicl image requirements when no backend is available."""
+    return [
+        "Qubicl image dependency pypdfium2",
+        "Qubicl image dependency poppler-utils (provides pdftoppm)",
+    ]
+
+
+def rasterize_page(pdf_path: str, page: int, dpi: int = 150, password: str | None = None):
+    """Render one 1-based page to a PIL Image, or None if no backend works.
+
+    Raises ValueError for an out-of-range page when a backend is present.
+    """
+    for backend in available_backends():
+        if backend == "pypdfium2":
+            return _via_pdfium(pdf_path, page, dpi, password)
+        if backend == "pdftoppm":
+            img = _via_pdftoppm(pdf_path, page, dpi, password)
+            if img is not None:
+                return img
+    return None
+
+
+def _via_pdfium(pdf_path: str, page: int, dpi: int, password: str | None):
+    import pypdfium2 as pdfium
+    doc = pdfium.PdfDocument(pdf_path, password=password)
+    try:
+        if not 1 <= page <= len(doc):
+            raise ValueError(f"page {page} out of range 1-{len(doc)}")
+        bitmap = doc[page - 1].render(scale=dpi / 72.0)
+        return bitmap.to_pil().convert("RGB")
+    finally:
+        doc.close()
+
+
+def _via_pdftoppm(pdf_path: str, page: int, dpi: int, password: str | None):
+    from PIL import Image
+    with tempfile.TemporaryDirectory() as tmp:
+        prefix = str(Path(tmp) / "page")
+        cmd = ["pdftoppm", "-png", "-r", str(dpi), "-f", str(page), "-l", str(page)]
+        if password:
+            cmd += ["-upw", password]
+        cmd += [pdf_path, prefix]
+        proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8")
+        if proc.returncode != 0:
+            raise ValueError(f"pdftoppm failed: {proc.stderr.strip()}")
+        produced = sorted(Path(tmp).glob("page*.png"))
+        if not produced:
+            raise ValueError(f"page {page} out of range (pdftoppm produced no image)")
+        with Image.open(produced[0]) as img:
+            return img.convert("RGB")

package/dist/assets/computer/skills/core/pdf/scripts/pdf_create.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Create a PDF from a JSON spec using reportlab platypus.
+
+Spec format (UTF-8 JSON):
+{
+  "title": "Example Report",
+  "author": "example-author",
+  "page_size": "A4",            // or "letter" (default: A4)
+  "page_numbers": true,          // default true
+  "elements": [
+    {"type": "heading", "text": "Section 1", "level": 1},
+    {"type": "paragraph", "text": "Body text..."},
+    {"type": "table", "rows": [["H1", "H2"], ["a", "b"]], "header": true},
+    {"type": "image", "path": "chart.png", "width": 400},
+    {"type": "pagebreak"}
+  ]
+}
+"""
+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 build_pdf(spec: dict, out_path: str) -> int:
+    try:
+        from reportlab.lib import colors
+        from reportlab.lib.pagesizes import A4, letter
+        from reportlab.lib.styles import getSampleStyleSheet
+        from reportlab.lib.units import inch
+        from reportlab.platypus import (
+            Image,
+            PageBreak,
+            Paragraph,
+            SimpleDocTemplate,
+            Spacer,
+            Table,
+            TableStyle,
+        )
+    except ImportError:
+        print("Required Qubicl PDF dependency is unavailable: reportlab", file=sys.stderr)
+        return 2
+
+    page_size = letter if str(spec.get("page_size", "A4")).lower() == "letter" else A4
+    styles = getSampleStyleSheet()
+    story = []
+    for el in spec.get("elements", []):
+        etype = el.get("type")
+        if etype == "heading":
+            level = min(max(int(el.get("level", 1)), 1), 3)
+            story.append(Paragraph(el.get("text", ""), styles[f"Heading{level}"]))
+        elif etype == "paragraph":
+            story.append(Paragraph(el.get("text", ""), styles["BodyText"]))
+            story.append(Spacer(1, 6))
+        elif etype == "table":
+            rows = el.get("rows", [])
+            if not rows:
+                continue
+            table = Table(rows, repeatRows=1 if el.get("header", True) else 0)
+            style = [
+                ("GRID", (0, 0), (-1, -1), 0.5, colors.grey),
+                ("VALIGN", (0, 0), (-1, -1), "TOP"),
+            ]
+            if el.get("header", True):
+                style += [
+                    ("BACKGROUND", (0, 0), (-1, 0), colors.lightgrey),
+                    ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
+                ]
+            table.setStyle(TableStyle(style))
+            story.append(table)
+            story.append(Spacer(1, 10))
+        elif etype == "image":
+            kwargs = {}
+            if el.get("width"):
+                kwargs["width"] = float(el["width"])
+            if el.get("height"):
+                kwargs["height"] = float(el["height"])
+            img = Image(el["path"], **kwargs)
+            if "width" in kwargs and "height" not in kwargs:
+                # keep aspect ratio
+                ratio = img.imageHeight / img.imageWidth
+                img.drawWidth = kwargs["width"]
+                img.drawHeight = kwargs["width"] * ratio
+            story.append(img)
+            story.append(Spacer(1, 10))
+        elif etype == "pagebreak":
+            story.append(PageBreak())
+        else:
+            print(f"Warning: unknown element type {etype!r}, skipped", file=sys.stderr)
+
+    def draw_page_number(canvas, doc):
+        if spec.get("page_numbers", True):
+            canvas.saveState()
+            canvas.setFont("Helvetica", 9)
+            canvas.drawCentredString(page_size[0] / 2.0, 0.5 * inch, f"Page {doc.page}")
+            canvas.restoreState()
+
+    doc = SimpleDocTemplate(
+        out_path,
+        pagesize=page_size,
+        title=spec.get("title", ""),
+        author=spec.get("author", ""),
+    )
+    doc.build(story, onFirstPage=draw_page_number, onLaterPages=draw_page_number)
+    print(json.dumps({"output": out_path, "elements": len(spec.get("elements", []))}))
+    return 0
+
+
+def main() -> int:
+    _reconfigure_stdio()
+    parser = argparse.ArgumentParser(description="Create a PDF from a JSON spec (reportlab).")
+    parser.add_argument("spec", help="Path to UTF-8 JSON spec file")
+    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_pdf(spec, args.output)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/assets/computer/skills/core/pdf/scripts/pdf_fill_form.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Fill AcroForm fields from a UTF-8 JSON file; optionally flatten.
+
+The JSON is a flat object: {"FieldName": "value", "Agree": true, ...}
+- text fields: strings
+- checkboxes: true/false (or an explicit on-state name like "/Yes")
+- radio / dropdown: the export value as a string (see pdf_read.py --fields "options")
+
+Sets NeedAppearances so conforming viewers regenerate field appearances.
+Flattening uses pypdf appearance merging; verify visually for exotic widgets.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+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="Fill PDF AcroForm fields from JSON (pypdf).")
+    parser.add_argument("pdf", help="Input form PDF")
+    parser.add_argument("--fields-json", required=True, help="UTF-8 JSON file of field values")
+    parser.add_argument("-o", "--output", required=True, help="Output PDF path")
+    parser.add_argument("--flatten", action="store_true",
+                        help="Make fields read-only and burn appearances into the page")
+    parser.add_argument("--password", help="Password if the input is encrypted")
+    args = parser.parse_args()
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+        from pypdf.generic import BooleanObject, NameObject
+    except ImportError:
+        print("Required Qubicl PDF dependency is unavailable: pypdf", file=sys.stderr)
+        return 2
+
+    with open(args.fields_json, encoding="utf-8") as fh:
+        values = json.load(fh)
+
+    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
+    available = set((reader.get_fields() or {}).keys())
+    missing = [name for name in values if name not in available]
+    if missing:
+        print(f"Warning: fields not found in form, skipped: {missing}", file=sys.stderr)
+
+    writer = PdfWriter()
+    writer.append(reader)
+
+    # Normalize checkbox booleans to the field's actual on-state name
+    # (e.g. "/Yes"): pypdf does not reliably map bare True to the on-state.
+    field_info = reader.get_fields() or {}
+    fill = {}
+    for name, value in values.items():
+        if name not in available:
+            continue
+        if isinstance(value, bool):
+            states = [str(s) for s in (field_info[name].get("/_States_") or [])]
+            on_state = next((s for s in states if s != "/Off"), "/Yes")
+            value = on_state if value else "/Off"
+        fill[name] = value
+    for page in writer.pages:
+        writer.update_page_form_field_values(page, fill, auto_regenerate=False)
+
+    # Set NeedAppearances so viewers render values even without appearance streams.
+    root = writer._root_object
+    if "/AcroForm" in root:
+        root["/AcroForm"][NameObject("/NeedAppearances")] = BooleanObject(True)
+
+    flattened = False
+    if args.flatten:
+        try:
+            # pypdf >= 5: flatten via update with flags making fields read-only,
+            # then remove interactivity by merging appearances.
+            for page in writer.pages:
+                writer.update_page_form_field_values(page, fill, flags=1)  # 1 = ReadOnly
+            flattened = True
+        except Exception as exc:
+            print(f"Warning: flatten step failed ({exc}); output keeps interactive fields",
+                  file=sys.stderr)
+
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps({"output": args.output, "filled": sorted(fill), "skipped": missing,
+                      "flattened": flattened}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/assets/computer/skills/core/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 the available Qubicl image or desktop tooling. 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())