Preface

When models need to read a local PDF, common approaches involve first extracting the text into the context or relying on external parsing services. Below is an introduction to sunshine-lang/dsh-pdf, a DeepSeek Harness (DSH) plugin: it parses PDFs locally, extracting text, metadata, and page ranges without requiring an API key or network access.

What is this

dsh-pdf is maintained by sunshine-lang under the MIT license. It provides a PDF toolbox for DSH, based on PDF.js / pdfjs-dist for local parsing, turning “reading PDF text, viewing titles and total pages, and fetching content by page range” into tools callable by the model.

Core Features

  • Provides the pdf_read tool to extract text page-by-page with page number markers.
  • Supports page range selection, such as "1-3,5" or "all".
  • Reads document metadata (title) and total pages.
  • Includes built-in limits for file byte size, pages parsed per call, and characters returned per call.
  • Reads PDFs via the harness file system seam (ctx.fs), with reading behavior constrained by the current dsh process’s permissions and sandbox policies.
  • Parses PDFs locally using PDF.js / pdfjs-dist, with no API key or network access required.

Installation and Enabling

The package.json requires Node >=22.19. When installing from GitHub, use:

dsh plugin --profile web add "github:sunshine-lang/dsh-pdf"

Dependencies are handled automatically when installing via the registry or GitHub. Local link: installations do not automatically install dependencies and require manual addition.

Typical Usage

After starting the Web UI, you can ask the model:

Read the first 3 pages of paper.pdf and summarize them.

Or inquire about specific pages:

What is written on page 7 of contract.pdf?

The model will call pdf_read. The path parameter is required; pages is optional and can be set to "1-3,5" or "all". For example:

{
  "path": "paper.pdf",
  "pages": "1-3"
}

When the output reaches the limit, it truncates at page boundaries and provides a hint; the model can continue reading with a page range.

Built-in Limits

dsh-pdf includes three configuration items related to reading scale:

  • maxFileBytes defaults to 20971520 (20 MiB), the byte limit for the entire PDF (inclusive); exceeding it causes an error.
  • maxPages defaults to 500, the maximum number of pages parsed per call; exceeding this truncates and provides a hint.
  • maxCharsPerCall defaults to 12000, the maximum characters returned per call; results are truncated at page boundaries.

If the configuration is invalid, the plugin fails to load and provides actionable error messages.

Use Cases and Notes

  • Suitable for reading local PDF text, viewing titles and total pages, and processing large documents in page-range chunks within DSH.
  • Since PDFs are read via ctx.fs, the plugin’s file reading is constrained by the current deployment’s permissions and sandbox policies; review the source code and license before installation.
  • Local link: installations do not automatically install dependencies; installations via the registry or GitHub handle this automatically.
  • Requires Node >=22.19.

Links

Repository: https://github.com/sunshine-lang/dsh-pdf