dsh-pdf-reader

DeepSeek Harness plugin for content-aware PDF reading by vision models.

The plugin reads a PDF the way its content demands: text-heavy pages are extracted as text, while figures, tables, formula-heavy or two-column pages are rendered as high-DPI region crops fed to the vision model — so a paper's vector figures and structured tables are never lost to the per-image token ceiling.

Backed by PyMuPDF. When Python or a dependency is missing, the tools return a clear, actionable warning (with the exact install command) for the agent to resolve, instead of failing hard.

Install

dsh plugin --profile web add dsh-pdf-reader

Requires a Python interpreter with pymupdf.

After installing Python, you can install the dsh-python-env plugin in DeepSeek Harness so the agent handles the dependency automatically — it will create a project venv and install pymupdf itself, with no manual steps:

dsh plugin --profile web add dsh-python-env

To set it up by hand instead:

python -m venv .venv
.venv\Scripts\python.exe -m pip install pymupdf

Tools

Tool	What it does
pdf_scan	Per-page content profile — columns, figures (vector regions), raster images, tables, text characters, hasGraphics, formulaRisk, hasTextLayer. Use first to decide how each page should be read.
pdf_read_page	Read one page the right way: pdf_scan's profile routes text pages to extraction and figure/table/math pages to a high-DPI region crop (path for read_image). mode=text / mode=render force a path.
pdf_render_region	Render a specific [x0,y0,x1,y1] region of a page to a PNG at budget-filling DPI (or an explicit dpi), returning its path for read_image.

Why this design

A two-column paper's figures are usually vector (only page rasterization can see them), tables lose structure under text extraction, and formulas garble in some text layers. Meanwhile DeepSeek caps each image at ~800×800-equivalent / 384 tokens — so reading a whole two-column page at that budget makes each column ~350px and loses small text, sub/superscripts and figure detail. The fix:

• Text pages → extraction (cheap, precise, preserves prose + inline math that PyMuPDF decodes well).
• Figure/table/math pages → render the region and scale it to fill the ~640k-pixel budget via dpi = 72 × sqrt(640000 / region_pt_area). Content is complete (nothing legible is lost inside the budget) and token-optimal (rendered AT the budget, not beyond it).

Region detection is heuristic (not a perfect classifier) and deliberately biased toward rendering — vector clusters from get_drawings(), raster rects from get_image_rects(), the same clustering for tables, and math from fonts + a LaTeX producer. It over-flags (a ruled table or a logo may be treated as a figure) rather than under-flagging, because rendering is cheap and safe.

When dependencies are missing

Each tool resolves a Python interpreter in priority order — the activated venv ($VIRTUAL_ENV) first, then PATH python/python3/py, then the project .venv/venv/env — probes it for pymupdf (and optionally pymupdf4llm), and picks the first one that can import it. If none can, it returns a warning naming what is missing and how to fix it, so the agent can install the dependency, switch interpreters, or fall back.

Limitations

• page.find_tables() false-positives on plot grids and diagrams, so tables are primarily read by rendering (the reliable path); Markdown tables from pymupdf4llm are a best-effort extra.
• Formula detection is heuristic (fonts + LaTeX producer). PyMuPDF decodes inline math well, but stacked fractions can still be imperfect — use pdf_render_region on an equation when exact structure is needed.
• A whole page renders to only ~83 DPI-equivalent at the budget; the tools never do that for a two-column page — they crop regions instead, and body text uses extraction.
• Large PDFs are parsed into memory.

Requirements

• Node ≥ 20, @deepseek-ai/cordis ^4, @deepseek-ai/dsh-tools (peer deps, provided by the harness).
• Python 3 + pymupdf (optional pymupdf4llm).

License

MIT