@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/work/vendor/hermes-agent/skills/productivity/docx/scripts/docx_validate.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Health-check a .docx package and report issues as JSON.
+
+Usage: docx_validate.py file.docx
+
+Checks (health-check tier, NOT full XSD schema validation):
+  - the file is a readable zip and python-docx can open it
+  - required package parts exist ([Content_Types].xml, document.xml)
+  - every relationship in every .rels file resolves to a part in the
+    package (dangling image/hyperlink/etc. rels are reported; external
+    targets such as hyperlinks are skipped)
+  - r:embed / r:id references in document.xml resolve to relationships
+  - embedded images are non-empty and start with known magic bytes
+    (PNG/JPEG/GIF/BMP/TIFF/EMF/WMF/SVG); no PIL required
+  - paragraph and run style ids referenced by the document exist in
+    styles.xml
+
+Output: {"ok": bool, "issues": [{"severity": "error"|"warning", ...}]}
+Exit code 1 when any error-severity issue is found (warnings exit 0).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import posixpath
+import sys
+import zipfile
+
+from lxml import etree
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+PR = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+IMAGE_MAGIC = (
+    b"\x89PNG\r\n\x1a\n", b"\xff\xd8\xff", b"GIF87a", b"GIF89a",
+    b"BM", b"II*\x00", b"MM\x00*",
+    b"\x01\x00\x00\x00",              # EMF
+    b"\xd7\xcd\xc6\x9a", b"\x01\x00\x09\x00",  # WMF variants
+    b"<?xml", b"<svg",
+)
+
+
+def _issue(issues, severity, code, detail):
+    issues.append({"severity": severity, "code": code, "detail": detail})
+
+
+def _rel_target(base_part: str, target: str) -> str:
+    base_dir = posixpath.dirname(base_part)
+    return posixpath.normpath(posixpath.join(base_dir, target)).lstrip("/")
+
+
+def validate(path: str) -> dict:
+    issues: list[dict] = []
+
+    try:
+        zf = zipfile.ZipFile(path)
+    except (OSError, zipfile.BadZipFile) as exc:
+        _issue(issues, "error", "not-a-zip", str(exc))
+        return {"ok": False, "issues": issues}
+
+    names = set(zf.namelist())
+    bad = zf.testzip()
+    if bad is not None:
+        _issue(issues, "error", "corrupt-member", f"CRC check failed: {bad}")
+
+    for required in ("[Content_Types].xml", "word/document.xml"):
+        if required not in names:
+            _issue(issues, "error", "missing-part",
+                   f"required part absent: {required}")
+    if issues and any(i["severity"] == "error" for i in issues):
+        return {"ok": False, "issues": issues}
+
+    # --- relationships resolve ------------------------------------------
+    rel_ids_by_source: dict[str, dict] = {}
+    for rels_name in [n for n in names if n.endswith(".rels")]:
+        try:
+            root = etree.fromstring(zf.read(rels_name))
+        except etree.XMLSyntaxError as exc:
+            _issue(issues, "error", "bad-rels-xml", f"{rels_name}: {exc}")
+            continue
+        source_part = posixpath.normpath(
+            posixpath.join(posixpath.dirname(rels_name), ".."))
+        source_part = "" if source_part == "." else source_part
+        ids = {}
+        for rel in root.iter(f"{{{PR}}}Relationship"):
+            rid, target = rel.get("Id"), rel.get("Target", "")
+            mode = rel.get("TargetMode", "Internal")
+            ids[rid] = target
+            if mode == "External":
+                continue
+            resolved = _rel_target(source_part + "/x" if source_part
+                                   else "x", target)
+            if resolved not in names:
+                _issue(issues, "error", "dangling-rel",
+                       f"{rels_name}: {rid} -> {target} (missing part)")
+        rel_ids_by_source[source_part or "_package"] = ids
+
+    # --- r:id / r:embed references in document.xml -----------------------
+    doc_root = etree.fromstring(zf.read("word/document.xml"))
+    doc_rels = rel_ids_by_source.get("word", {})
+    for el in doc_root.iter():
+        for attr in (f"{{{R}}}id", f"{{{R}}}embed", f"{{{R}}}link"):
+            rid = el.get(attr)
+            if rid and rid not in doc_rels:
+                _issue(issues, "error", "unresolved-reference",
+                       f"document.xml references {rid} with no relationship")
+
+    # --- embedded images decode ------------------------------------------
+    for name in [n for n in names if n.startswith("word/media/")]:
+        data = zf.read(name)
+        if not data:
+            _issue(issues, "error", "empty-image", name)
+        elif not any(data.startswith(m) for m in IMAGE_MAGIC):
+            _issue(issues, "warning", "unknown-image-format",
+                   f"{name}: unrecognized magic bytes")
+
+    # --- styles referenced exist ------------------------------------------
+    defined = set()
+    if "word/styles.xml" in names:
+        styles_root = etree.fromstring(zf.read("word/styles.xml"))
+        defined = {s.get(f"{{{W}}}styleId")
+                   for s in styles_root.iter(f"{{{W}}}style")}
+    for tag, attr in ((f"{{{W}}}pStyle", f"{{{W}}}val"),
+                      (f"{{{W}}}rStyle", f"{{{W}}}val"),
+                      (f"{{{W}}}tblStyle", f"{{{W}}}val")):
+        for el in doc_root.iter(tag):
+            sid = el.get(attr)
+            if sid and sid not in defined:
+                _issue(issues, "error", "missing-style",
+                       f"style id referenced but not defined: {sid}")
+
+    # --- python-docx can open it ------------------------------------------
+    try:
+        from docx import Document
+        Document(path)
+    except Exception as exc:  # noqa: BLE001 - triage tool, report anything
+        _issue(issues, "error", "python-docx-open-failed", str(exc))
+
+    ok = not any(i["severity"] == "error" for i in issues)
+    return {"ok": ok, "issues": issues}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Health-check a .docx (not XSD schema validation).")
+    ap.add_argument("path", help="the .docx file to check")
+    args = ap.parse_args()
+    report = validate(args.path)
+    print(json.dumps(report, ensure_ascii=False))
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/work/vendor/hermes-agent/skills/productivity/pdf/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/work/vendor/hermes-agent/skills/productivity/pdf/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: pdf
+description: "PDF files: create, read, merge, fill, OCR, edit text."
+version: 1.1.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [pdf, documents, forms, ocr, text-extraction, reportlab, pypdf, pdfplumber, pymupdf, marker]
+    category: productivity
+    related_skills: [docx, xlsx, powerpoint]
+---
+
+# PDF Skill
+
+Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks):
+
+- **Scanned/image-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): `references/ocr-extraction.md`
+- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references/nano-pdf-editing.md`
+
+## When to Use
+
+- Generate a report, invoice, or multi-page document as PDF.
+- Build a fillable AcroForm (text/checkbox/radio/dropdown) from a JSON spec, linting the layout first.
+- Pull text, tables (JSON/CSV), metadata, or form-field values out of a PDF.
+- Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs.
+- Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments.
+- Fill or flatten AcroForm forms; encrypt or decrypt with passwords.
+- NOT for scanned/image-only PDFs (use `references/ocr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).
+
+## Prerequisites
+
+- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`:
+  `python -m pip install pypdf reportlab pdfplumber`
+- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `python -m pip install pypdfium2`, or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{"rendered": false, "missing": [...]}` (exit 0) when neither exists.
+- Each helper script checks imports lazily and prints an install hint if a dependency is missing.
+
+## How to Run
+
+All helpers live in `scripts/` and are argparse CLIs — run them with the `terminal` tool; every one supports `--help`. They read/write JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure.
+
+```bash
+python scripts/pdf_create.py spec.json -o out.pdf         # build PDF from JSON spec
+python scripts/pdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec
+python scripts/pdf_form_layout.py formspec.json           # lint form layout BEFORE building
+python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
+python scripts/pdf_read.py doc.pdf --text                 # per-page text (JSON)
+python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # tables to JSON + CSV files
+python scripts/pdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted/scanned flags
+python scripts/pdf_read.py form.pdf --fields              # form fields: name, type, value
+python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]
+python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]
+python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]
+python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password
+python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password
+python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]
+python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 \
+    --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3]
+python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
+python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/
+python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf
+python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
+python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/
+```
+
+## Quick Reference
+
+| Task | Tool | Command / API |
+|---|---|---|
+| Create doc (headings, tables, images) | reportlab platypus | `pdf_create.py spec.json -o out.pdf` |
+| Build fillable form | reportlab acroForm | `pdf_make_form.py formspec.json -o form.pdf` |
+| Lint form layout / overlay image | pure python + PIL | `pdf_form_layout.py formspec.json [--render-overlay o.png]` |
+| Per-page text | pdfplumber | `pdf_read.py f.pdf --text` |
+| Tables → JSON/CSV | pdfplumber | `pdf_read.py f.pdf --tables` |
+| Metadata / sizes / encrypted / scanned | pypdf + pdfplumber | `pdf_read.py f.pdf --meta` |
+| Merge (+ outline) | pypdf | `pdf_merge.py a.pdf b.pdf -o m.pdf` |
+| Split / extract / rotate | pypdf | `pdf_split.py f.pdf --pages 2-5 --rotate 90` |
+| List / fill / flatten form | pypdf | `pdf_read.py --fields`, `pdf_fill_form.py` |
+| Encrypt / decrypt (AES-256) | pypdf | `pdf_secure.py --encrypt/--decrypt` |
+| Watermark / stamp PDF page | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` |
+| Stamp text/image at coordinates | reportlab + pypdf | `pdf_stamp.py f.pdf --text "Sign here" --x 400 --y 60` |
+| Pages → PNG (review / OCR hand-off) | pypdfium2 or pdftoppm | `pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/` |
+| Set/clear metadata, attachments | pypdf | `pdf_meta.py --set-meta / --attach / --extract-attachments` |
+| Compress content streams | pypdf | `pdf_split.py f.pdf --pages 1-N --compress` |
+
+## Procedure
+
+1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, export them with `pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/` and hand the PNGs to the `references/ocr-extraction.md` skill — do not report empty text as "no content".
+2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`/`author` metadata; page numbers are added automatically), then run `pdf_create.py`. Verify visually with `vision_analyze` on a rendered page image if layout matters.
+3. **Extract.** `--text` gives a JSON list of per-page strings; `--tables` gives row arrays per page and can also emit CSV files. Read results with `read_file`; never eyeball a binary PDF directly.
+4. **Manipulate.** `pdf_merge.py` concatenates and can add one bookmark per source file; `pdf_split.py` handles page ranges (1-based, e.g. `1-3,5,9-`), rotation in 90° steps, and `--compress`. Watermark by preparing a single-page stamp PDF (e.g. via `pdf_create.py`) and overlaying it with `pdf_watermark.py`; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use `pdf_stamp.py` with text or an image at explicit coordinates.
+5. **Build forms.** Write one form-spec JSON (fields with `label_box`/`entry_box` in PDF points — see `references/forms.md`), lint it with `pdf_form_layout.py` and fix every reported problem, optionally review the `--render-overlay` PNG with `vision_analyze`, then build with `pdf_make_form.py` and confirm with `pdf_read.py --fields`.
+6. **Fill forms.** List fields (`--fields`) to learn exact names and types, write a UTF-8 JSON of `{"FieldName": "value"}` with `write_file` (checkboxes accept `true`/`false`; radio/choice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed.
+7. **Metadata & attachments.** `pdf_meta.py --set-meta` writes Title/Author/Subject/Keywords (DocInfo); `--clear-meta` drops them; `--attach`/`--list-attachments`/`--extract-attachments` round-trip embedded files.
+8. **Secure.** Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy.
+9. **Verify** (see below) before reporting success.
+
+## Pitfalls
+
+- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references/ocr-extraction.md`; do not fabricate text.
+- **Flattening limits**: `pdf_fill_form.py --flatten` uses pypdf's flatten support, which converts widget appearances into page content. It is reliable for plain text fields and checkboxes but can drop or misrender exotic widgets (rich text, custom appearance streams, some radio groups). Verify the flattened output visually with `vision_analyze`; for bulletproof flattening use an external renderer (e.g. Ghostscript or `pdftoppm`+reassembly) as a fallback.
+- **NeedAppearances**: after filling, viewers only render values if appearance streams exist. The fill script sets the AcroForm `NeedAppearances` flag so conforming viewers regenerate them; some minimal viewers ignore it — flatten if display fidelity matters.
+- **Non-Latin form values**: values are stored correctly (UTF-16), but the field's default font may lack glyphs, so a viewer can show blanks even though the data round-trips. Verify with `--fields`, not just visually.
+- **Compression expectations**: `--compress` only deflates content streams. Typical savings are 0–20%; it does nothing for PDFs dominated by images or already-compressed streams. It is not a substitute for image downsampling (Ghostscript territory).
+- **Permission flags don't enforce**: owner-password permission bits (no-print, no-copy) are polite requests that viewers may honor; any library (including pypdf) can read and strip them. Only the user password actually gates content via encryption. Never present permission flags as security.
+- **Table extraction is heuristic**: pdfplumber detects tables from ruling lines/word alignment; borderless or merged-cell tables may need `table_settings` tuning or manual cleanup.
+- **Page indexing**: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert.
+- **Rotated stamp text extraction**: pdfplumber's line grouping scrambles rotated glyphs (a 45° "DRAFT" extracts as stray letters); verify rotated stamps with `pypdf`'s `extract_text()` or a rendered image instead.
+- **Radio groups**: reportlab needs ≥2 `radio()` widgets per group, fills need the slashed export value (`"/red"`), and flatten fidelity is worst for radios — see `references/forms.md`.
+- **Metadata scope**: `pdf_meta.py` writes the classic DocInfo dictionary only; embedded XMP metadata (if any) is left untouched and may show different values in some viewers.
+- **PDF/A is out of scope**: pypdf/reportlab cannot produce or validate conformant PDF/A. If archival conformance is required, run Ghostscript via the `terminal` tool (e.g. `gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf` with a suitable ICC profile) and validate with veraPDF — both are external installs, and the result still needs validation, not assumption.
+- Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation.
+
+## Verification
+
+- After create/merge/split: `pdf_read.py out.pdf --meta` — confirm `page_count`, and per-page `rotation` when you rotated.
+- After extraction: check the JSON is non-empty and spot-check a known string or cell.
+- Form design loop: `pdf_form_layout.py spec.json` must exit 0; then `--render-overlay boxes.png --pdf form.pdf` and review the PNG with `vision_analyze` (red = entry boxes with field names, blue = label boxes) asking about overlaps, misalignment, and labels detached from their fields. Iterate spec → lint → overlay until clean.
+- After building a form: `pdf_read.py form.pdf --fields` lists every spec field with the right type and options.
+- After form fill: `pdf_read.py filled.pdf --fields` and compare values (exact match, including non-ASCII).
+- After stamping: re-extract text (pypdf for rotated stamps) or render the page with `pdf_page_image.py` and inspect with `vision_analyze`.
+- After metadata/attachment edits: `pdf_read.py --meta` / `pdf_meta.py --list-attachments`, and re-extract an attachment to byte-compare.
+- After encrypt: `--meta` shows `"encrypted": true` and opening without a password fails; after decrypt, text extraction matches the original.
+- For anything visual (watermarks, flattened forms), render and inspect with `vision_analyze`.

package/work/vendor/hermes-agent/skills/productivity/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]:
+    """Install hints for when no backend is available."""
+    return [
+        "python3 -m pip install pypdfium2",
+        "poppler-utils (provides pdftoppm), e.g. apt-get install poppler-utils",
+    ]
+
+
+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/work/vendor/hermes-agent/skills/productivity/pdf/scripts/extract_marker.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Extract text from documents using marker-pdf. High-quality OCR + layout analysis.
+
+Requires ~3-5GB disk (PyTorch + models downloaded on first use).
+Supports: PDF, DOCX, PPTX, XLSX, HTML, EPUB, images.
+
+Usage:
+    python extract_marker.py document.pdf
+    python extract_marker.py document.pdf --output_dir ./output
+    python extract_marker.py presentation.pptx
+    python extract_marker.py spreadsheet.xlsx
+    python extract_marker.py scanned_doc.pdf           # OCR works here
+    python extract_marker.py document.pdf --json        # Structured output
+    python extract_marker.py document.pdf --use_llm     # LLM-boosted accuracy
+"""
+import sys
+import os
+
+def convert(path, output_dir=None, output_format="markdown", use_llm=False):
+    from marker.converters.pdf import PdfConverter
+    from marker.models import create_model_dict
+    from marker.config.parser import ConfigParser
+
+    config_dict = {}
+    if use_llm:
+        config_dict["use_llm"] = True
+
+    config_parser = ConfigParser(config_dict)
+    models = create_model_dict()
+    converter = PdfConverter(config=config_parser.generate_config_dict(), artifact_dict=models)
+    rendered = converter(path)
+
+    if output_format == "json":
+        import json
+        print(json.dumps({
+            "markdown": rendered.markdown,
+            "metadata": rendered.metadata if hasattr(rendered, "metadata") else {},
+        }, indent=2, ensure_ascii=False))
+    else:
+        print(rendered.markdown)
+
+    # Save images if output_dir specified
+    if output_dir and hasattr(rendered, "images") and rendered.images:
+        from pathlib import Path
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
+        for name, img_data in rendered.images.items():
+            img_path = os.path.join(output_dir, name)
+            with open(img_path, "wb") as f:
+                f.write(img_data)
+        print(f"\nSaved {len(rendered.images)} image(s) to {output_dir}/", file=sys.stderr)
+
+
+def check_requirements():
+    """Check disk space before installing."""
+    import shutil
+    free_gb = shutil.disk_usage("/").free / (1024**3)
+    if free_gb < 5:
+        print(f"⚠️  Only {free_gb:.1f}GB free. marker-pdf needs ~5GB for PyTorch + models.")
+        print("Use pymupdf instead (scripts/extract_pymupdf.py) or free up disk space.")
+        sys.exit(1)
+    print(f"✓ {free_gb:.1f}GB free — sufficient for marker-pdf")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Extract text from documents using marker-pdf (high-quality OCR + layout analysis)."
+    )
+    parser.add_argument("path", nargs="?", help="Document to convert (PDF, DOCX, PPTX, XLSX, HTML, EPUB, image)")
+    parser.add_argument("--output_dir", help="Directory to save extracted images")
+    parser.add_argument("--json", action="store_true", help="Structured JSON output instead of markdown")
+    parser.add_argument("--use_llm", action="store_true", help="LLM-boosted accuracy")
+    parser.add_argument("--check", action="store_true", help="Check disk space requirements and exit")
+    args = parser.parse_args()
+
+    if args.check:
+        check_requirements()
+        sys.exit(0)
+    if not args.path:
+        parser.error("path is required unless --check is given")
+
+    convert(
+        args.path,
+        output_dir=args.output_dir,
+        output_format="json" if args.json else "markdown",
+        use_llm=args.use_llm,
+    )

package/work/vendor/hermes-agent/skills/productivity/pdf/scripts/extract_pymupdf.py

@@ -0,0 +1,101 @@
+#!/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 < len(doc):
+            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):
+    import pymupdf
+    doc = pymupdf.open(path)
+    for i, page in enumerate(doc):
+        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):
+    import pymupdf
+    from pathlib import Path
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    doc = pymupdf.open(path)
+    count = 0
+    for i, page in enumerate(doc):
+        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 args.metadata:
+        show_metadata(args.path)
+    elif args.tables:
+        extract_tables(args.path)
+    elif args.images is not None:
+        extract_images(args.path, args.images)
+    elif args.markdown:
+        extract_markdown(args.path, pages=pages)
+    else:
+        extract_text(args.path, pages=pages)