doc-redaction 2.2.2__tar.gz → 2.2.3__tar.gz

{doc_redaction-2.2.2/doc_redaction.egg-info → doc_redaction-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: doc_redaction
-Version: 2.2.2
+Version: 2.2.3
 Summary: Redact PDF/image-based documents, Word, or CSV/XLSX files using a Gradio-based GUI interface
 Author-email: Sean Pedrick-Case <spedrickcase@lambeth.gov.uk>
 Maintainer-email: Sean Pedrick-Case <spedrickcase@lambeth.gov.uk>

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/app.py

@@ -9432,7 +9432,7 @@ If you are an LLM/agent calling this app programmatically, prefer the **short `g
         ],
         show_progress=True,
         show_progress_on=[summarisation_status],
-        api_name="undocumented",
+        api_visibility="undocumented",
     ).success(
         fn=lambda: "summarisation",
         outputs=[task_textbox],
@@ -10105,6 +10105,7 @@ If you are an LLM/agent calling this app programmatically, prefer the **short `g
     from tools.simplified_api import (
         doc_redact_api,
         pdf_summarise_api,
+        preview_boxes_api,
         review_apply_api,
         tabular_redact_api,
     )
@@ -10145,6 +10146,18 @@ If you are an LLM/agent calling this app programmatically, prefer the **short `g
         ),
     )
 
+    gr.api(
+        preview_boxes_api,
+        api_name="preview_boxes",
+        api_description=(
+            "Render proposed redaction boxes from a *_review_file.csv onto the original PDF "
+            "and return a ZIP of preview PNGs. Use this to verify box positions before calling "
+            "/review_apply — no redaction is applied. "
+            "Returns (zip_path, message). For agents with local files, calling "
+            "tools.preview_redaction_boxes.preview_redaction_boxes() directly is faster."
+        ),
+    )
+
     ###
     # APP RUN SETTINGS
     ###

{doc_redaction-2.2.2 → doc_redaction-2.2.3/doc_redaction.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: doc_redaction
-Version: 2.2.2
+Version: 2.2.3
 Summary: Redact PDF/image-based documents, Word, or CSV/XLSX files using a Gradio-based GUI interface
 Author-email: Sean Pedrick-Case <spedrickcase@lambeth.gov.uk>
 Maintainer-email: Sean Pedrick-Case <spedrickcase@lambeth.gov.uk>

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/doc_redaction.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ tools/llm_entity_detection_prompts.py
 tools/llm_funcs.py
 tools/load_spacy_model_custom_recognisers.py
 tools/presidio_analyzer_custom.py
+tools/preview_redaction_boxes.py
 tools/quickstart.py
 tools/redaction_review.py
 tools/redaction_types.py

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "doc_redaction"
-version = "2.2.2"
+version = "2.2.3"
 description = "Redact PDF/image-based documents, Word, or CSV/XLSX files using a Gradio-based GUI interface"
 readme = "README_PYPI.md"
 authors = [

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/tools/config.py

@@ -587,8 +587,8 @@ LOAD_REDACTION_ANNOTATIONS_FROM_PDF = convert_string_to_boolean(
 TESSERACT_FOLDER = get_or_create_env_var(
     "TESSERACT_FOLDER", ""
 )  #  # If installing for Windows, install Tesseract 5.5.0 from here: https://github.com/UB-Mannheim/tesseract/wiki. Then this environment variable should point to the Tesseract folder e.g. tesseract/
-if TESSERACT_FOLDER:
-    TESSERACT_FOLDER = ensure_folder_within_app_directory(TESSERACT_FOLDER)
+if TESSERACT_FOLDER and not os.path.isabs(TESSERACT_FOLDER):
+    # TESSERACT_FOLDER = ensure_folder_within_app_directory(TESSERACT_FOLDER)
     add_folder_to_path(TESSERACT_FOLDER)
 
 TESSERACT_DATA_FOLDER = get_or_create_env_var(
@@ -601,7 +601,7 @@ if TESSERACT_DATA_FOLDER and not os.path.isabs(TESSERACT_DATA_FOLDER):
 POPPLER_FOLDER = get_or_create_env_var(
     "POPPLER_FOLDER", ""
 )  # If installing on Windows,install Poppler from here https://github.com/oschwartz10612/poppler-windows. This variable needs to point to the poppler bin folder e.g. poppler/poppler-24.02.0/Library/bin/
-if POPPLER_FOLDER:
+if POPPLER_FOLDER and not os.path.isabs(POPPLER_FOLDER):
     POPPLER_FOLDER = ensure_folder_within_app_directory(POPPLER_FOLDER)
     add_folder_to_path(POPPLER_FOLDER)
 
@@ -2157,6 +2157,30 @@ MERGE_SMALL_REDACTIONS = convert_string_to_boolean(
     get_or_create_env_var("MERGE_SMALL_REDACTIONS", "False")
 )
 
+# When True (and MERGE_SMALL_REDACTIONS), only merge boxes that are on the same visual text line.
+# Implemented as a required minimum vertical overlap ratio between the two boxes.
+#
+# This prevents pathological merges where two separate redactions on different lines get unioned into
+# one huge rectangle (e.g., if the merge threshold is large relative to the coordinate scale).
+MERGE_SMALL_REDACTIONS_SAME_LINE_ONLY = convert_string_to_boolean(
+    get_or_create_env_var("MERGE_SMALL_REDACTIONS_SAME_LINE_ONLY", "True")
+)
+
+# Minimum vertical overlap ratio (0–1) required for two boxes to be considered "same line" for merging.
+# Ratio is computed as overlap_height / min(height1, height2).
+try:
+    _merge_small_redactions_min_y_overlap_ratio = float(
+        get_or_create_env_var(
+            "MERGE_SMALL_REDACTIONS_MIN_Y_OVERLAP_RATIO", "0.6"
+        ).strip()
+        or "0.6"
+    )
+except ValueError:
+    _merge_small_redactions_min_y_overlap_ratio = 0.6
+MERGE_SMALL_REDACTIONS_MIN_Y_OVERLAP_RATIO = max(
+    0.0, min(1.0, _merge_small_redactions_min_y_overlap_ratio)
+)
+
 # When True, use Polars for review DataFrame coordinate scaling and CSV write in apply_redactions_to_review_df_and_files (faster for large annotation sets).
 USE_POLARS_FOR_REVIEW = convert_string_to_boolean(
     get_or_create_env_var("USE_POLARS_FOR_REVIEW", "True")

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/tools/custom_image_analyser_engine.py

@@ -7,6 +7,7 @@ import math
 import os
 import re
 import shutil
+import sys
 import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
@@ -158,6 +159,22 @@ def _guess_tessdata_dir_from_tesseract_exe(tesseract_exe: str | None) -> str | N
     return None
 
 
+def _strip_wrapping_quotes(path: str | None) -> str:
+    """
+    Some .env setups accidentally include quotes in values, e.g.:
+      TESSDATA_PREFIX="tesseract/tessdata"
+    If those quotes end up in the environment variable value (including a stray trailing quote),
+    Tesseract will literally try to open paths like '"..."/eng.traineddata' and fail.
+    """
+    if not path:
+        return ""
+    s = str(path).strip()
+    if len(s) >= 2 and ((s[0] == s[-1] == '"') or (s[0] == s[-1] == "'")):
+        return s[1:-1].strip()
+    # Also handle common "one-sided" cases, e.g. a stray trailing quote.
+    return s.strip('"').strip("'").strip()
+
+
 def _resolve_tessdata_dir() -> str | None:
     """
     Return an absolute tessdata directory if we can find one.
@@ -166,15 +183,16 @@ def _resolve_tessdata_dir() -> str | None:
     2) tools.config.TESSERACT_DATA_FOLDER if it points to a valid tessdata dir
     3) Guess based on tesseract executable location (PATH / pytesseract config)
     """
-    env_prefix = os.environ.get("TESSDATA_PREFIX", "")
+    env_prefix = _strip_wrapping_quotes(os.environ.get("TESSDATA_PREFIX", ""))
     if _is_probable_tessdata_dir(env_prefix):
         return os.path.abspath(env_prefix)
 
     try:
         from tools.config import TESSERACT_DATA_FOLDER
 
-        if _is_probable_tessdata_dir(TESSERACT_DATA_FOLDER):
-            return os.path.abspath(TESSERACT_DATA_FOLDER)
+        cfg_dir = _strip_wrapping_quotes(TESSERACT_DATA_FOLDER)
+        if _is_probable_tessdata_dir(cfg_dir):
+            return os.path.abspath(cfg_dir)
     except Exception:
         # config import is optional for library use
         pass
@@ -195,11 +213,20 @@ def _ensure_tessdata_available_in_env(existing_config: str | None) -> str | None
     if not tessdata_dir:
         return existing_config
 
-    os.environ.setdefault("TESSDATA_PREFIX", tessdata_dir)
+    # Overwrite (not setdefault) so we can repair misquoted values already present in env.
+    os.environ["TESSDATA_PREFIX"] = tessdata_dir
 
     cfg = (existing_config or "").strip()
     if "--tessdata-dir" in cfg:
         return cfg
+
+    # On Windows, pytesseract parses config with shlex(posix=False), which can
+    # preserve quote characters in values and make Tesseract treat them as part
+    # of the path (e.g. '"C:\\...\\tessdata"/eng.traineddata'). Rely on
+    # TESSDATA_PREFIX there instead of injecting --tessdata-dir.
+    if sys.platform == "win32":
+        return cfg
+
     return (cfg + f' --tessdata-dir "{tessdata_dir}"').strip()
 
 

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/tools/file_redaction.py

@@ -82,6 +82,8 @@ from tools.config import (
     MAX_WORKERS,
     MERGE_BOUNDING_BOXES,
     MERGE_SMALL_REDACTIONS,
+    MERGE_SMALL_REDACTIONS_MIN_Y_OVERLAP_RATIO,
+    MERGE_SMALL_REDACTIONS_SAME_LINE_ONLY,
     NO_REDACTION_PII_OPTION,
     OCR_FIRST_PASS_MAX_WORKERS,
     OUTPUT_FOLDER,
@@ -4987,7 +4989,27 @@ def _merge_adjacent_redaction_boxes(
         out["ymax"] = max(b1["ymax"], b2["ymax"])
         return out
 
+    def _y_overlap_ratio(b1: dict, b2: dict) -> float:
+        h1 = max(0.0, float(b1["ymax"]) - float(b1["ymin"]))
+        h2 = max(0.0, float(b2["ymax"]) - float(b2["ymin"]))
+        denom = min(h1, h2)
+        if denom <= 0:
+            return 0.0
+        overlap = max(
+            0.0,
+            min(float(b1["ymax"]), float(b2["ymax"]))
+            - max(float(b1["ymin"]), float(b2["ymin"])),
+        )
+        return overlap / denom
+
     def _overlap_or_close(b1: dict, b2: dict) -> bool:
+        # Guard rail: do not merge across separate visual lines unless explicitly allowed.
+        # This prevents a single giant union box when two redactions happen to be consecutive
+        # in reading order but are located on very different y positions.
+        if MERGE_SMALL_REDACTIONS_SAME_LINE_ONLY:
+            if _y_overlap_ratio(b1, b2) < MERGE_SMALL_REDACTIONS_MIN_Y_OVERLAP_RATIO:
+                return False
+
         if b1["xmax"] + threshold < b2["xmin"] or b2["xmax"] + threshold < b1["xmin"]:
             return False
         if b1["ymax"] + threshold < b2["ymin"] or b2["ymax"] + threshold < b1["ymin"]:

doc_redaction-2.2.3/tools/preview_redaction_boxes.py

@@ -0,0 +1,323 @@
+"""
+preview_redaction_boxes.py
+==========================
+Local-first coordinate preview tool for the Document Redaction app.
+
+Purpose
+-------
+Render proposed redaction boxes from a ``*_review_file.csv`` onto the
+**original** (un-redacted) PDF pages and save the result as PNG images.
+Because this runs entirely locally with PyMuPDF + Pillow, iteration is
+instantaneous — no server round-trip, no waiting for ``/review_apply``.
+
+Primary use-case
+----------------
+Called by agents or humans **between CSV edits and the API call to
+``/review_apply``**.  Iterate until the preview looks right, *then*
+send to the server.  This avoids the expensive cycle of:
+
+    guess coordinates → apply → download → render → spot the miss → repeat
+
+Typical agent workflow
+----------------------
+1. Edit ``*_review_file_edited.csv`` (remove FPs, add signatures, etc.).
+2. Call ``preview_redaction_boxes(pdf_path, csv_path, out_dir)`` locally.
+3. Inspect the saved PNGs.
+4. If anything is wrong, adjust the CSV and go to step 2.
+5. Only when satisfied, call ``/review_apply`` on the server.
+
+API endpoint (server-side fallback)
+------------------------------------
+When the agent does not have a local copy of the original PDF,
+``preview_boxes_api()`` exposes the same logic as a short ``gr.api``
+endpoint registered as ``/preview_boxes`` in ``app.py``.  The caller
+uploads the original PDF and the edited review CSV; the server returns a
+ZIP of preview PNGs.
+
+CLI usage
+---------
+    python tools/preview_redaction_boxes.py original.pdf review_file.csv
+
+    # Optional flags:
+    python tools/preview_redaction_boxes.py original.pdf review_file.csv \\
+        --out-dir output/preview \\
+        --dpi 150 \\
+        --max-width 1280 \\
+        --grid            # draw percentage-grid lines
+        --pages 1,3,5     # only render specific pages (1-indexed)
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import Sequence
+
+import pymupdf
+from PIL import Image, ImageDraw, ImageFont
+
+# ── Colour palette per label type ──────────────────────────────────────────
+_LABEL_COLOURS: dict[str, str] = {
+    "PERSON": "#e74c3c",  # red
+    "SIGNATURE": "#8e44ad",  # purple
+    "LOCATION": "#2980b9",  # blue
+    "EMAIL_ADDRESS": "#e67e22",  # orange
+    "PHONE_NUMBER": "#27ae60",  # green
+    "CUSTOM": "#f39c12",  # amber
+    "DATE_TIME": "#16a085",  # teal
+    "ORG": "#7f8c8d",  # grey
+}
+_DEFAULT_COLOUR = "#c0392b"
+
+# ── Grid style ─────────────────────────────────────────────────────────────
+_GRID_COLOUR = "#cc0000"
+_GRID_STEP = 5  # percentage intervals
+
+
+def _label_colour(label: str) -> str:
+    for key, colour in _LABEL_COLOURS.items():
+        if key in label.upper():
+            return colour
+    return _DEFAULT_COLOUR
+
+
+def _load_font(size: int = 11) -> ImageFont.ImageFont:
+    """Return a PIL font; fall back to the default if no TTF is available."""
+    for name in ("DejaVuSans.ttf", "Arial.ttf", "LiberationSans-Regular.ttf"):
+        try:
+            return ImageFont.truetype(name, size)
+        except OSError:
+            pass
+    return ImageFont.load_default()
+
+
+def preview_redaction_boxes(
+    pdf_path: str | Path,
+    csv_path: str | Path,
+    out_dir: str | Path | None = None,
+    *,
+    dpi: int = 150,
+    max_width: int = 1280,
+    draw_grid: bool = True,
+    pages: Sequence[int] | None = None,
+) -> list[Path]:
+    """
+    Render proposed redaction boxes from *csv_path* onto the original PDF
+    at *pdf_path* and save one PNG per page to *out_dir*.
+
+    Parameters
+    ----------
+    pdf_path:
+        Path to the original (un-redacted) PDF.
+    csv_path:
+        Path to the ``*_review_file.csv`` (original or edited).
+    out_dir:
+        Directory for output PNGs.  Defaults to a ``preview/`` subfolder
+        next to the CSV.
+    dpi:
+        Render resolution.  150 is a good balance of speed vs. detail.
+        Use 200-300 for detailed inspection of small text.
+    max_width:
+        Downscale rendered pages to at most this width (pixels) before
+        drawing boxes, to keep file sizes manageable.
+    draw_grid:
+        If True, overlay horizontal lines at every *_GRID_STEP* percent of
+        page height with percentage labels so you can read off normalized
+        y-coordinates by eye.
+    pages:
+        If given, only render these 1-indexed page numbers.  Useful when
+        you are iterating on a single page and don't want to wait for the
+        whole document.
+
+    Returns
+    -------
+    list[Path]
+        Sorted list of saved PNG paths.
+    """
+    pdf_path = Path(pdf_path)
+    csv_path = Path(csv_path)
+
+    if out_dir is None:
+        out_dir = csv_path.parent / "preview"
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # ── Load CSV ────────────────────────────────────────────────────────────
+    with csv_path.open(newline="", encoding="utf-8-sig") as fh:
+        rows = list(csv.DictReader(fh))
+
+    rows_by_page: dict[int, list[dict]] = {}
+    for row in rows:
+        try:
+            page_num = int(float(row.get("page", "0") or 0))
+        except ValueError:
+            continue
+        rows_by_page.setdefault(page_num, []).append(row)
+
+    # ── Render pages ────────────────────────────────────────────────────────
+    doc = pymupdf.open(str(pdf_path))
+    font = _load_font(11)
+    saved: list[Path] = []
+
+    page_range = range(1, doc.page_count + 1)
+    if pages:
+        page_range = [p for p in pages if 1 <= p <= doc.page_count]
+
+    for page_num in page_range:
+        pix = doc[page_num - 1].get_pixmap(dpi=dpi)
+        render_w, render_h = pix.width, pix.height
+
+        img = Image.frombytes("RGB", [render_w, render_h], pix.samples)
+
+        # ── Downscale if needed ──────────────────────────────────────────
+        if render_w > max_width:
+            scale = max_width / render_w
+            img = img.resize((max_width, int(render_h * scale)), Image.LANCZOS)
+        draw_w, draw_h = img.size
+
+        draw = ImageDraw.Draw(img, "RGBA")
+
+        # ── Percentage grid ──────────────────────────────────────────────
+        if draw_grid:
+            for pct in range(0, 101, _GRID_STEP):
+                y = int(pct / 100 * draw_h)
+                draw.line([(0, y), (draw_w, y)], fill=_GRID_COLOUR + "55", width=1)
+                draw.text((3, max(0, y - 11)), f"{pct}%", fill=_GRID_COLOUR, font=font)
+
+        # ── Redaction boxes ──────────────────────────────────────────────
+        for row in rows_by_page.get(page_num, []):
+            try:
+                x0 = float(row["xmin"]) * draw_w
+                y0 = float(row["ymin"]) * draw_h
+                x1 = float(row["xmax"]) * draw_w
+                y1 = float(row["ymax"]) * draw_h
+            except (KeyError, ValueError):
+                continue
+
+            label = row.get("label", "CUSTOM")
+            colour = _label_colour(label)
+            text_snippet = (row.get("text", "") or "")[:30]
+
+            # Semi-transparent fill
+            draw.rectangle(
+                [x0, y0, x1, y1], fill=colour + "33", outline=colour, width=2
+            )
+
+            # Label text
+            tag = f"{label}: {text_snippet}" if text_snippet else label
+            draw.text((x0 + 3, y0 + 2), tag, fill=colour, font=font)
+
+        # ── Legend (top-right corner) ────────────────────────────────────
+        legend_labels = sorted(
+            {r.get("label", "CUSTOM") for r in rows_by_page.get(page_num, [])}
+        )
+        lx, ly = draw_w - 200, 8
+        for lbl in legend_labels:
+            col = _label_colour(lbl)
+            draw.rectangle(
+                [lx, ly, lx + 14, ly + 14], fill=col + "cc", outline=col, width=1
+            )
+            draw.text((lx + 18, ly + 1), lbl, fill=col, font=font)
+            ly += 17
+
+        out_path = out_dir / f"page_{page_num:03d}_preview.png"
+        img.save(out_path)
+        saved.append(out_path)
+
+    doc.close()
+    print(f"Saved {len(saved)} preview image(s) to: {out_dir}")
+    return sorted(saved)
+
+
+def preview_redaction_boxes_to_zip(
+    pdf_path: str | Path,
+    csv_path: str | Path,
+    *,
+    dpi: int = 150,
+    max_width: int = 1280,
+    draw_grid: bool = True,
+    pages: Sequence[int] | None = None,
+) -> bytes:
+    """
+    Same as ``preview_redaction_boxes`` but returns a ZIP of PNGs as bytes.
+
+    Used by the ``preview_boxes_api`` server endpoint so callers receive
+    all preview images in a single response without needing a shared
+    filesystem.
+    """
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        paths = preview_redaction_boxes(
+            pdf_path,
+            csv_path,
+            out_dir=tmp,
+            dpi=dpi,
+            max_width=max_width,
+            draw_grid=draw_grid,
+            pages=pages,
+        )
+        buf = BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            for p in paths:
+                zf.write(p, arcname=Path(p).name)
+        return buf.getvalue()
+
+
+# ── CLI entry-point ─────────────────────────────────────────────────────────
+def _main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Render proposed redaction boxes from a review CSV onto the original PDF."
+    )
+    parser.add_argument("pdf", help="Path to the original (un-redacted) PDF")
+    parser.add_argument("csv", help="Path to the *_review_file.csv")
+    parser.add_argument(
+        "--out-dir",
+        default=None,
+        help="Output directory for PNGs (default: <csv-dir>/preview/)",
+    )
+    parser.add_argument(
+        "--dpi", type=int, default=150, help="Render DPI (default: 150)"
+    )
+    parser.add_argument(
+        "--max-width",
+        type=int,
+        default=1280,
+        help="Max image width in pixels (default: 1280)",
+    )
+    parser.add_argument(
+        "--grid",
+        action="store_true",
+        default=True,
+        help="Draw percentage grid (default: on)",
+    )
+    parser.add_argument(
+        "--no-grid", dest="grid", action="store_false", help="Disable percentage grid"
+    )
+    parser.add_argument(
+        "--pages",
+        default=None,
+        help="Comma-separated 1-indexed page numbers to render, e.g. 1,3,5 (default: all)",
+    )
+    args = parser.parse_args()
+
+    pages = None
+    if args.pages:
+        pages = [int(p.strip()) for p in args.pages.split(",")]
+
+    preview_redaction_boxes(
+        args.pdf,
+        args.csv,
+        out_dir=args.out_dir,
+        dpi=args.dpi,
+        max_width=args.max_width,
+        draw_grid=args.grid,
+        pages=pages,
+    )
+
+
+if __name__ == "__main__":
+    _main()

{doc_redaction-2.2.2 → doc_redaction-2.2.3}/tools/simplified_api.py

@@ -1077,6 +1077,104 @@ def tabular_redact_api(
     )
 
 
+def preview_boxes_api(
+    pdf_file: Any,
+    review_csv_file: Any,
+    dpi: int | None = 150,
+    max_width: int | None = 1280,
+    draw_grid: bool | None = True,
+    pages: str | None = None,
+) -> tuple[str, str]:
+    """
+    Render proposed redaction boxes from *review_csv_file* onto the
+    original *pdf_file* and return a ZIP archive of preview PNGs.
+
+    Use this endpoint when you do **not** have a local copy of the
+    original PDF and want to verify box positions without calling
+    ``/review_apply``.  For agents that already hold local files,
+    calling ``tools.preview_redaction_boxes.preview_redaction_boxes``
+    directly is faster (no upload/download round-trip).
+
+    Parameters
+    ----------
+    pdf_file:
+        The original (un-redacted) PDF uploaded by the caller.
+    review_csv_file:
+        The ``*_review_file.csv`` (original or edited) uploaded by the
+        caller.
+    dpi:
+        Render resolution (default 150).
+    max_width:
+        Maximum output image width in pixels (default 1280).
+    draw_grid:
+        If True (default), overlay percentage-grid lines so normalized
+        y-coordinates can be read by eye.
+    pages:
+        Optional comma-separated 1-indexed page numbers, e.g. ``"1,3,5"``.
+        If omitted, all pages are rendered.
+
+    Returns
+    -------
+    tuple[str, str]
+        ``(zip_path, message)`` where *zip_path* is a server-side path to
+        a ZIP file of preview PNGs retrievable via
+        ``GET /gradio_api/file=<zip_path>``.
+    """
+    import tempfile
+
+    from tools.preview_redaction_boxes import preview_redaction_boxes
+
+    pdf_path = normalize_gradio_file_to_path(pdf_file)
+    csv_path = normalize_gradio_file_to_path(review_csv_file)
+
+    if not pdf_path or not csv_path:
+        return "", "Error: both pdf_file and review_csv_file are required."
+
+    pdf_path = stage_gradio_upload_if_ephemeral(pdf_path, INPUT_FOLDER)
+    csv_path = stage_gradio_upload_if_ephemeral(csv_path, INPUT_FOLDER)
+
+    page_list: list[int] | None = None
+    if pages:
+        try:
+            page_list = [int(p.strip()) for p in pages.split(",") if p.strip()]
+        except ValueError:
+            return (
+                "",
+                f"Error: 'pages' must be comma-separated integers, got: {pages!r}",
+            )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        out_paths = preview_redaction_boxes(
+            pdf_path,
+            csv_path,
+            out_dir=tmp,
+            dpi=int(dpi or 150),
+            max_width=int(max_width or 1280),
+            draw_grid=bool(draw_grid),
+            pages=page_list,
+        )
+
+        if not out_paths:
+            return (
+                "",
+                "No pages rendered — check that the CSV contains rows with valid page numbers.",
+            )
+
+        out_base = Path(OUTPUT_FOLDER) / f"preview_{Path(pdf_path).stem}"
+        out_base.mkdir(parents=True, exist_ok=True)
+        zip_path = str(out_base / "preview_boxes.zip")
+
+        import zipfile
+
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for p in out_paths:
+                zf.write(p, arcname=Path(p).name)
+
+    n = len(out_paths)
+    msg = f"Preview complete: {n} page(s) rendered. Download the ZIP to inspect box positions."
+    return zip_path, msg
+
+
 def doc_redact_api(
     document_file: Any,
     redact_entities: list[str] | None = None,
@@ -1117,4 +1215,5 @@ __all__ = [
     "run_apply_review_redactions",
     "summarise_document_from_upload_for_gradio_api",
     "pdf_summarise_api",
+    "preview_boxes_api",
 ]