@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/office-artifacts/references/pdf/scripts/extract_pymupdf.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Extract text from documents using pymupdf. Lightweight (~25MB), no models.
+
+Usage:
+    python extract_pymupdf.py document.pdf
+    python extract_pymupdf.py document.pdf --markdown
+    python extract_pymupdf.py document.pdf --pages 0-4
+    python extract_pymupdf.py document.pdf --images output_dir/
+    python extract_pymupdf.py document.pdf --tables
+    python extract_pymupdf.py document.pdf --metadata
+"""
+import sys
+import json
+
+def extract_text(path, pages=None):
+    import pymupdf
+    doc = pymupdf.open(path)
+    page_range = range(len(doc)) if pages is None else pages
+    for i in page_range:
+        if i < 0 or i >= len(doc): raise ValueError('page out of range')
+        print(f"\n--- Page {i+1}/{len(doc)} ---\n")
+        print(doc[i].get_text())
+
+def extract_markdown(path, pages=None):
+    import pymupdf4llm
+    md = pymupdf4llm.to_markdown(path, pages=pages)
+    print(md)
+
+def extract_tables(path, pages=None):
+    import pymupdf
+    doc = pymupdf.open(path)
+    for i in (range(len(doc)) if pages is None else pages):
+        if i < 0 or i >= len(doc): raise ValueError('page out of range')
+        page = doc[i]
+        tables = page.find_tables()
+        for j, table in enumerate(tables.tables):
+            print(f"\n--- Page {i+1}, Table {j+1} ---\n")
+            df = table.to_pandas()
+            print(df.to_markdown(index=False))
+
+def extract_images(path, output_dir, pages=None):
+    import pymupdf
+    from pathlib import Path
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    doc = pymupdf.open(path)
+    count = 0
+    for i in (range(len(doc)) if pages is None else pages):
+        if i < 0 or i >= len(doc): raise ValueError('page out of range')
+        page = doc[i]
+        for img_idx, img in enumerate(page.get_images(full=True)):
+            xref = img[0]
+            pix = pymupdf.Pixmap(doc, xref)
+            if pix.n >= 5:
+                pix = pymupdf.Pixmap(pymupdf.csRGB, pix)
+            out_path = f"{output_dir}/page{i+1}_img{img_idx+1}.png"
+            pix.save(out_path)
+            count += 1
+    print(f"Extracted {count} images to {output_dir}/")
+
+def show_metadata(path):
+    import pymupdf
+    doc = pymupdf.open(path)
+    print(json.dumps({
+        "pages": len(doc),
+        "title": doc.metadata.get("title", ""),
+        "author": doc.metadata.get("author", ""),
+        "subject": doc.metadata.get("subject", ""),
+        "creator": doc.metadata.get("creator", ""),
+        "producer": doc.metadata.get("producer", ""),
+        "format": doc.metadata.get("format", ""),
+    }, indent=2))
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Extract text/tables/images/metadata from documents using pymupdf (lightweight, no models)."
+    )
+    parser.add_argument("path", help="Document to read")
+    parser.add_argument("--pages", help="Page selection: N or START-END (0-indexed)")
+    parser.add_argument("--markdown", action="store_true", help="Markdown output via pymupdf4llm")
+    parser.add_argument("--tables", action="store_true", help="Extract tables as markdown")
+    parser.add_argument("--images", nargs="?", const="./images", metavar="OUTPUT_DIR",
+                        help="Extract embedded images to OUTPUT_DIR (default ./images)")
+    parser.add_argument("--metadata", action="store_true", help="Show document metadata as JSON")
+    args = parser.parse_args()
+
+    pages = None
+    if args.pages:
+        if "-" in args.pages:
+            start, end = args.pages.split("-")
+            pages = list(range(int(start), int(end) + 1))
+        else:
+            pages = [int(args.pages)]
+        if not pages or min(pages) < 0:
+            parser.error('page selection must be nonempty and nonnegative')
+
+    if args.metadata:
+        show_metadata(args.path)
+    elif args.tables:
+        extract_tables(args.path, pages=pages)
+    elif args.images is not None:
+        extract_images(args.path, args.images, pages=pages)
+    elif args.markdown:
+        extract_markdown(args.path, pages=pages)
+    else:
+        extract_text(args.path, pages=pages)

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_create.py

@@ -0,0 +1,153 @@
+#!/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("Missing dependency: install with 'python3 -m pip install reportlab'", file=sys.stderr)
+        return 2
+
+    page_size = letter if str(spec.get("page_size", "A4")).lower() == "letter" else A4
+    styles = getSampleStyleSheet()
+    font_name = 'Helvetica'
+    texts = [str(el.get('text', '')) for el in spec.get('elements', [])]
+    texts.extend(str(cell) for el in spec.get('elements', []) for row in el.get('rows', []) for cell in row)
+    if spec.get('font_file'):
+        from reportlab.pdfbase import pdfmetrics
+        from reportlab.pdfbase.ttfonts import TTFont
+        font_name = 'PrismerDocumentFont'
+        font = TTFont(font_name, spec['font_file'])
+        missing = {ord(c) for text in texts for c in text if not c.isspace() and ord(c) not in font.face.charToGlyph}
+        if missing:
+            print('Error: selected font lacks required glyphs', file=sys.stderr)
+            return 2
+        pdfmetrics.registerFont(font)
+        pdfmetrics.registerFontFamily(font_name, normal=font_name, bold=font_name, italic=font_name, boldItalic=font_name)
+        for style in styles.byName.values():
+            style.fontName = font_name
+    else:
+        try:
+            for text in texts: text.encode('cp1252')
+        except UnicodeEncodeError:
+            print('Error: Unicode content requires font_file with verified glyph coverage', file=sys.stderr)
+            return 2
+    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 = [
+                ("FONTNAME", (0, 0), (-1, -1), font_name),
+                ("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), font_name if spec.get('font_file') else "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/built-in-skills/office-artifacts/references/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("Missing dependency: install with 'python3 -m pip install 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:
+            for page in writer.pages:
+                writer.update_page_form_field_values(page, fill, auto_regenerate=False, flatten=True)
+            writer.remove_annotations(subtypes='/Widget')
+            writer._root_object.pop('/AcroForm', None)
+            flattened = True
+        except Exception as exc:
+            print(f"Error: flatten failed ({exc}); no output written", file=sys.stderr)
+            return 4
+
+    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/built-in-skills/office-artifacts/references/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/built-in-skills/office-artifacts/references/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())