dsh-chatpaper

Readme

# dsh-chatpaper

After DSH's release, I plan to gradually accumulate the tools I use frequently as DSH plugins.

ChatPaper has brought me a lot of convenience — it saves a great deal of time searching for papers and doing research. So, to adapt it into a DSH plugin, I spent some time modifying the code with AI and published it to GitHub, hoping to bring the same convenience to more people.

arXiv paper tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), provided as **native tools** — no Python, no MCP server. Paper text is extracted primarily from **arXiv's official HTML rendering** (LaTeXML), with ar5iv and PDF fallbacks.

This project is a DSH plugin port referencing [ChatPaper](https://github.com/kaixindelele/ChatPaper): the tool contracts and query logic are kept consistent, but it now runs directly on DeepSeek Harness's native interfaces. See [Acknowledgments](#acknowledgments) at the end for the source and citation.

## Tools

| Tool | What it does |
|---|---|
| `search_arxiv` | Search arXiv. Natural language (e.g. "agent as a judge") is matched as an `all:` phrase, falling back to an AND match over its content words when nothing is found; native arXiv query syntax (`ti:transformer`, `cat:cs.CL AND all:agent`) passes through untouched. |
| `summarize_paper` | Download a paper, extract its text, and summarize it with an LLM under fixed headings (Background, Methods, Results, Conclusions). |
| `translate_paper` | Translate a paper's full text chunk by chunk; long papers can run in the background. |
| `generate_survey` | Write a literature survey from search results — abstract-level (fast) or full-text deep mode (one summary per paper, concurrent, background-capable). |

Background runs (`run_in_background: true`) register standard DSH jobs: the call returns a job id immediately, and after completion the result (or failure detail) is retrieved with the harness's built-in `job_output` tool. A single read is capped at 20000 bytes.

`search_arxiv` needs no API key. The three LLM-backed tools use the **harness LLM service** (`ctx.llm`) — the provider, model, credentials, retry policy, and routing configured on the web Models page are all reused directly, with nothing to configure inside the plugin. When `provider`/`model` are left empty, they resolve at call time to the deployment's deepseek route and its default model; explicit configuration takes precedence.

## Install

From npm (prebuilt, no install-time build authorization needed):

```sh
dsh plugin --profile <name> add dsh-chatpaper
```

From GitHub source (runs a `prepare` build; pnpm requires an `allowBuilds` grant in the profile's `pnpm-workspace.yaml` — the npm route is preferred):

```sh
dsh plugin --profile <name> add github:puppet2004/dsh-chatpaper
```

The bundle registers one `chatpaper` row; after installation, every session of that profile sees these 4 tools.

## Configuration

Add or override the row in your profile's `cordis.patch.yml`:

```yaml
- insert:
    - id: chatpaper
      name: dsh-chatpaper
      config:
        provider: ''
        model: ''
```

| Key | Default | Description |
|---|---|---|
| `provider` | `''` | Harness LLM provider route; empty resolves to the deployment's deepseek route (`deepseek-official` in the official deployment). |
| `model` | `''` | Harness LLM model id; empty resolves to the adapter's advertised default model. |
| `cacheDir` | `~/.dsh-chatpaper-cache` | Paper-body cache directory, keyed by versioned arXiv id. |
| `surveyConcurrency` | `4` | Concurrent per-paper summaries in deep survey mode. |
| `summaryChars` | `15000` | Text slice fed to a summary. |
| `surveyPaperChars` | `8000` | Text slice fed to a deep-survey per-paper summary. |
| `translateChunkChars` | `6000` | Size of one translation chunk. |
| `translateMaxChars` | `60000` | Cap on source characters to translate. |
| `searchDelayMs` | `3000` | Delay before each arXiv API request (rate-limit courtesy). |
| `searchRetries` | `3` | arXiv API retry count. |
| `downloadTimeoutMs` | `120000` | Paper-body download timeout. |

## How paper text is fetched

1. **Official HTML** — `https://arxiv.org/html/<versioned-id>`; structured extraction preserves section headings and math (`<math alttext>` → LaTeX).
2. **ar5iv** — `https://ar5iv.labs.arxiv.org/html/<id>` for older papers without official HTML.
3. **PDF fallback** — `pdfjs-dist` text extraction for papers with no HTML at all.

Each tier's output is validated (an empty shell or fewer than 200 extracted characters falls through to the next tier). Extracted text is cached, so repeated calls are instant.

## Model Experience

### What the model sees

4 native tools with their declared schemas. `search_arxiv` returns structured paper metadata (id, title, authors, date, categories, pdf URL, abstract) rendered as a numbered list. The LLM tools return structured results whose render shows the summary/translation/survey text; surveys also carry an `[n]`-indexed reference list.

### Token and KV-cache effects

Tool schemas are fixed, so the model-facing definition prefix is stable across requests. Tool results are plain text; no binary or image payloads enter context. Paper bodies are truncated (`summaryChars`/`surveyPaperChars`/`translateMaxChars`) before every LLM call, keeping prompts bounded. Cache hits avoid re-downloading and re-extracting entirely.

## Acknowledgments

This project is a port of the open-source **ChatPaper** project. The search query logic, paper-summarization prompts, and survey workflow follow the original design, re-implemented on DeepSeek Harness native interfaces (`ctx.llm`, `ctx.tools`, `ctx.jobs`). Thanks a lot for ChatPaper's work. If you use this plugin or build on it, please also cite the original project:

```bibtex
@misc{ChatPaper,
  author={Yongle Luo, Rongsheng Wang, Peter Gam, Jiaxi Cui, circlestarzero, Shiwen Ni, Jaseon Quanta, Qingxu Fu, Siyuan Hou},
  title = {ChatPaper: Use LLM to summarize papers.},
  year = {2023},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/kaixindelele/ChatPaper}},
}
```