@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/office-artifacts/references/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/built-in-skills/office-artifacts/references/pdf/NOTICE.md

@@ -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/built-in-skills/office-artifacts/references/pdf/references/forms.md

@@ -0,0 +1,99 @@
+# 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 install hints). Feed the PNG to `vision_analyze`
+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/built-in-skills/office-artifacts/references/pdf/references/nano-pdf-editing.md

@@ -0,0 +1,40 @@
+# Natural-language PDF text editing with nano-pdf (merged from the nano-pdf skill)
+# nano-pdf
+
+Edit PDFs using natural-language instructions. Point it at a page and describe what to change. For structural PDF work (merge, split, forms, watermarks, creation), see the `pdf` skill; for text extraction from scans, see `ocr-and-documents`.
+
+## Prerequisites
+
+```bash
+# Install with uv (recommended — already available in Hermes)
+uv pip install nano-pdf
+
+# Or with pip
+pip install nano-pdf
+```
+
+## Usage
+
+```bash
+nano-pdf edit <file.pdf> <page_number> "<instruction>"
+```
+
+## Examples
+
+```bash
+# Change a title on page 1
+nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"
+
+# Update a date on a specific page
+nano-pdf edit report.pdf 3 "Update the date from January to February 2026"
+
+# Fix content
+nano-pdf edit contract.pdf 2 "Change the client name from 'Acme Corp' to 'Acme Industries'"
+```
+
+## Notes
+
+- Page numbers may be 0-based or 1-based depending on version — if the edit hits the wrong page, retry with ±1
+- Always verify the output PDF after editing (use `read_file` to check file size, or open it)
+- The tool uses an LLM under the hood — requires an API key (check `nano-pdf --help` for config)
+- Works well for text changes; complex layout modifications may need a different approach

package/built-in-skills/office-artifacts/references/pdf/references/ocr-extraction.md

@@ -0,0 +1,165 @@
+# OCR & Document Text Extraction (merged from the ocr-and-documents skill)
+
+Scripts referenced below live in this skill's scripts/ directory.
+# PDF & Document Extraction
+
+For DOCX: see the `docx` skill (create/edit) or use `python-docx` for structured reads.
+For PPTX: see the `powerpoint` skill (full create/read/edit support).
+For PDF manipulation (merge, split, forms, watermarks, creation): see the `pdf` skill.
+This skill covers **text extraction from PDFs and scanned documents**.
+
+> **Coming from a `read_file` EXTRACTION COVERAGE WARNING?** `read_file` auto-converts local PDFs but reads the text layer only; the warning footer lists the pages that yielded no text (scanned images). For a handful of pages, render + vision is fastest: `pdftoppm -jpeg -r 150 -f N -l N file.pdf $TMPDIR/page` then `vision_analyze` each image. For bulk OCR of many pages, use marker-pdf below (Step 2).
+
+## Step 1: Remote URL Available?
+
+If the document has a URL, **always try `web_extract` first**:
+
+```
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+web_extract(urls=["https://example.com/report.pdf"])
+```
+
+This handles PDF-to-markdown conversion via Firecrawl with no local dependencies.
+
+Only use local extraction when: the file is local, web_extract fails, or you need batch processing.
+
+## Step 2: Choose Local Extractor
+
+| Feature | pymupdf (~25MB) | marker-pdf (~3-5GB) |
+|---------|-----------------|---------------------|
+| **Text-based PDF** | ✅ | ✅ |
+| **Scanned PDF (OCR)** | ❌ | ✅ (90+ languages) |
+| **Tables** | ✅ (basic) | ✅ (high accuracy) |
+| **Equations / LaTeX** | ❌ | ✅ |
+| **Code blocks** | ❌ | ✅ |
+| **Forms** | ❌ | ✅ |
+| **Headers/footers removal** | ❌ | ✅ |
+| **Reading order detection** | ❌ | ✅ |
+| **Images extraction** | ✅ (embedded) | ✅ (with context) |
+| **Images → text (OCR)** | ❌ | ✅ |
+| **EPUB** | ✅ | ✅ |
+| **Markdown output** | ✅ (via pymupdf4llm) | ✅ (native, higher quality) |
+| **Install size** | ~25MB | ~3-5GB (PyTorch + models) |
+| **Speed** | Instant | ~1-14s/page (CPU), ~0.2s/page (GPU) |
+
+**Decision**: Use pymupdf unless you need OCR, equations, forms, or complex layout analysis.
+
+If the user needs marker capabilities but the system lacks ~5GB free disk:
+> "This document needs OCR/advanced extraction (marker-pdf), which requires ~5GB for PyTorch and models. Your system has [X]GB free. Options: free up space, provide a URL so I can use web_extract, or I can try pymupdf which works for text-based PDFs but not scanned documents or equations."
+
+---
+
+## pymupdf (lightweight)
+
+```bash
+pip install pymupdf pymupdf4llm
+```
+
+**Via helper script**:
+```bash
+python scripts/extract_pymupdf.py document.pdf              # Plain text
+python scripts/extract_pymupdf.py document.pdf --markdown    # Markdown
+python scripts/extract_pymupdf.py document.pdf --tables      # Tables
+python scripts/extract_pymupdf.py document.pdf --images out/ # Extract images
+python scripts/extract_pymupdf.py document.pdf --metadata    # Title, author, pages
+python scripts/extract_pymupdf.py document.pdf --pages 0-4   # Specific pages
+```
+
+**Inline**:
+```bash
+python -c "
+import pymupdf
+doc = pymupdf.open('document.pdf')
+for page in doc:
+    print(page.get_text())
+"
+```
+
+---
+
+## marker-pdf (high-quality OCR)
+
+```bash
+# Check disk space first
+python scripts/extract_marker.py --check
+
+pip install marker-pdf
+```
+
+**Via helper script**:
+```bash
+python scripts/extract_marker.py document.pdf                # Markdown
+python scripts/extract_marker.py document.pdf --json         # JSON with metadata
+python scripts/extract_marker.py document.pdf --output_dir out/  # Save images
+python scripts/extract_marker.py scanned.pdf                 # Scanned PDF (OCR)
+python scripts/extract_marker.py document.pdf --use_llm      # LLM-boosted accuracy
+```
+
+**CLI** (installed with marker-pdf):
+```bash
+marker_single document.pdf --output_dir ./output
+marker /path/to/folder --workers 4    # Batch
+```
+
+---
+
+## Arxiv Papers
+
+```
+# Abstract only (fast)
+web_extract(urls=["https://arxiv.org/abs/2402.03300"])
+
+# Full paper
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+
+# Search
+web_search(query="arxiv GRPO reinforcement learning 2026")
+```
+
+## Split, Merge & Search
+
+pymupdf handles these natively — use `execute_code` or inline Python:
+
+```python
+# Split: extract pages 1-5 to a new PDF
+import pymupdf
+doc = pymupdf.open("report.pdf")
+new = pymupdf.open()
+for i in range(5):
+    new.insert_pdf(doc, from_page=i, to_page=i)
+new.save("pages_1-5.pdf")
+```
+
+```python
+# Merge multiple PDFs
+import pymupdf
+result = pymupdf.open()
+for path in ["a.pdf", "b.pdf", "c.pdf"]:
+    result.insert_pdf(pymupdf.open(path))
+result.save("merged.pdf")
+```
+
+```python
+# Search for text across all pages
+import pymupdf
+doc = pymupdf.open("report.pdf")
+for i, page in enumerate(doc):
+    results = page.search_for("revenue")
+    if results:
+        print(f"Page {i+1}: {len(results)} match(es)")
+        print(page.get_text("text"))
+```
+
+No extra dependencies needed — pymupdf covers split, merge, search, and text extraction in one package.
+
+---
+
+## Notes
+
+- `web_extract` is always first choice for URLs
+- pymupdf is the safe default — instant, no models, works everywhere
+- marker-pdf is for OCR, scanned docs, equations, complex layouts — install only when needed
+- Both helper scripts accept `--help` for full usage
+- marker-pdf downloads ~2.5GB of models to `~/.cache/huggingface/` on first use
+- For Word docs: `pip install python-docx` (better than OCR — parses actual structure)
+- For PowerPoint: see the `powerpoint` skill (uses python-pptx)

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

@@ -0,0 +1,87 @@
+"""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.
+    """
+    if page < 1 or not 1 <= dpi <= 600:
+        raise ValueError('page must be positive and dpi in 1..600')
+    errors = []
+    for backend in available_backends():
+        if backend == "pypdfium2":
+            try:
+                return _via_pdfium(pdf_path, page, dpi, password)
+            except ValueError:
+                raise
+            except Exception as exc:
+                errors.append(str(exc))
+                continue
+        if backend == "pdftoppm":
+            img = _via_pdftoppm(pdf_path, page, dpi, password)
+            if img is not None:
+                return img
+    if errors:
+        raise RuntimeError('No usable renderer: ' + '; '.join(errors))
+    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", timeout=120)
+        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/built-in-skills/office-artifacts/references/pdf/scripts/extract_marker.py

@@ -0,0 +1,95 @@
+#!/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
+    from marker.output import text_from_rendered
+
+    config_dict = {'output_format': output_format}
+    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,
+                             renderer=config_parser.get_renderer(),
+                             processor_list=config_parser.get_processors(),
+                             llm_service=config_parser.get_llm_service())
+    rendered = converter(path)
+    text, _, images = text_from_rendered(rendered)
+
+    if output_format == "json":
+        import json
+        print(json.dumps(rendered.model_dump(), indent=2, ensure_ascii=False))
+    else:
+        print(text)
+
+    # Save images if output_dir specified
+    if output_dir and images:
+        from pathlib import Path
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
+        for name, img_data in images.items():
+            safe = Path(name.replace('\\', '/')).name
+            if safe in ('', '.', '..'): raise ValueError('invalid image name')
+            img_path = os.path.join(output_dir, safe)
+            with open(img_path, "xb") as f:
+                if hasattr(img_data, 'save'):
+                    img_data.save(f, format='PNG')
+                else:
+                    f.write(img_data)
+        print(f"\nSaved {len(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/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)