# DeepXiv SDK: an agentic CLI and Python client for arXiv papers

> DeepXiv wraps a hosted literature service in a Python package: papers arrive pre-parsed into sections, retrieval runs over full bodies, and answers come back with arXiv IDs. The trade-off is that the heavy lifting happens on someone else's server.

**DeepXiv/deepxiv_sdk** — Talk to research papers like talking to authors - Python package with AI agent for arXiv papers

- Repository: https://github.com/DeepXiv/deepxiv_sdk
- Website: https://data.rag.ac.cn/api/docs
- Stars: 800 · Forks: 45
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/deepxiv-deepxiv-sdk

## The token budget problem DeepXiv SDK is built around

An agent that needs a specific number from a paper has two bad options. A search API returns titles and abstracts, which is enough to name a paper and not enough to answer "what speedup does it report on HumanEval". A PDF answers the question but costs roughly 50k tokens and arrives as unstructured text with no way to jump to the section you need.

DeepXiv's claim is that this trade-off is unnecessary because the parsing work can be done once, upstream, and reused. The README states that papers arrive parsed into sections rather than PDFs, and that retrieval runs over full bodies rather than abstracts. That reframes the agent's decision: spend about 300 tokens on a TLDR to judge a paper, then about 5k on the Methods section, or stop entirely. The unit of reading becomes the section, not the document.

The intended user is a developer or researcher wiring literature access into an agent, not someone browsing for a paper to read. The four commands map to four questions: what does the literature say (ask), what does this paper say (paper), what else is out there (search), and who wrote it (talent).

## How the hosted service and the local package divide the work

The split matters more than the command list. The pip package is a client. Parsing, indexing, retrieval and the agentic loop all run on the service at data.rag.ac.cn, and the SDK's job is to send requests, stream responses back, and expose them as Python objects.

That shows up in the dependency list. The base install pulls in requests, click and python-dotenv, which is a thin HTTP client plus a CLI. There is an optional agent extra with openai, langgraph and langchain-core, but the core path does not need it, which tells you the agentic reasoning happens server-side rather than in your process.

It also shows up in the output contract. The README notes that for deepxiv ask the answer goes to stdout and sources go to stderr, so redirecting stdout captures the answer alone. That is a deliberate choice for shell pipelines and for agents that parse the result. The web backend follows the same pattern: it reads cached page bodies, and pages read in full are marked differently from snippet-only ones so the caller can weigh them.

The Python entry point is a Reader object that takes the token explicitly, exposing agent_search, section and talent_search. Same pipeline, no subprocess.

## Installing deepxiv-sdk and running a first cited query

The package installs from PyPI under the name deepxiv-sdk, while the command it puts on your path is deepxiv.

```bash
pip install deepxiv-sdk
```

There is a caveat in the README: deepxiv talent is not on PyPI yet and ships in version 1.1.0b1 from source while the scholar index is still being built out. If you need that command, install from the repository instead.

```bash
pip install git+https://github.com/DeepXiv/deepxiv_sdk.git
```

The CLI registers a token automatically on first use, but the agentic commands (ask and talent) need a registered key. The README points to data.rag.ac.cn/register, after which you configure it once:

```bash
deepxiv config --token YOUR_REGISTERED_KEY
```

With that in place, a first real query is a question rather than a keyword. The service chooses its own tools, reads paper bodies, and cites what it used.

```bash
deepxiv ask "what speedup does speculative decoding report on HumanEval in 2025"
```

The README's example output names a paper, reports a speedup figure against a named benchmark, and lists the arXiv ID as a source. Sources print to stderr, so you can capture only the answer:

```bash
deepxiv ask "what speedup does speculative decoding report on HumanEval in 2025" > answer.md
```

From there, the layered read is the part worth adopting first. Run --brief for a TLDR, --head for the section list, then --section with a name taken from that list. Section names are not standardized across papers, which is why --head exists.

## Where the design costs you something

The hosted architecture is the main limitation, and it is not incidental. Parsing, indexing and the agentic loop run on the service, so there is no offline mode described anywhere in the README. If your queries are sensitive, or if you need the tool to work inside an air-gapped environment, this is the wrong shape entirely.

The quota is the second constraint. Every account gets 300 agentic calls per day free, on a pool separate from the general daily limit. That is a real ceiling. A batch job that asks a question per paper will hit it quickly, and the README does not document what happens at the boundary or how to raise it.

The third is filter behavior. Search filters combine with AND, and the README is direct about the consequence: stack too many and you will legitimately get zero results. That is honest documentation of a design that will surprise people who expect filters to widen a result set.

Finally, talent is explicitly beta. It is not on PyPI, it requires a source install, and the README says the scholar index is still being built out. Do not build a workflow that depends on it today.

## How this differs from Semantic Scholar and plain PDF pipelines

Semantic Scholar is the closest well-known comparison, and the difference is in what each one returns. Semantic Scholar is primarily a metadata and graph API: it gives you papers, authors, citations and abstracts, and you assemble the reading yourself. DeepXiv's pitch is the opposite end of that pipeline. It returns an answer with citations, and its paper command returns parsed section text rather than an abstract, which is the part Semantic Scholar's API does not give you.

The second alternative is doing it yourself: download PDFs, run a parser, chunk the text, embed it, and put a retrieval layer in front. That gives you full control, works offline, and lets you index anything, not just arXiv. It also means owning a parsing and indexing pipeline and paying the token cost per document unless you build caching. DeepXiv is essentially that pipeline, pre-built and hosted, with the corresponding loss of control.

The choice is not about which is more capable. It is about whether you want to operate the pipeline or call it.

## Maintenance, licence and what an upgrade commits you to

The repository is not archived and the last push was on 2026-09-04, so the code is being touched recently. The version in setup.py is 1.1.0b1 and the classifier is Development Status 3 - Alpha, which is worth reading literally: the API surface may move, and the talent command is documented as still under construction.

The licence is MIT, which is permissive and places few obligations on how you use or redistribute the SDK. That covers the client code. It does not tell you anything about the hosted service's terms, and the README does not describe them. If you are planning to route production traffic through data.rag.ac.cn, the service terms are a separate question from the licence, and this material does not answer it.

Upgrade cost is low on the client side, since the base dependencies are requests, click and python-dotenv. The real exposure is behavioral: changes to the hosted service can alter what a query returns without any version bump in the package you installed.

## Conclusion

Adopt DeepXiv SDK if your work involves reading many arXiv papers and you want section-level retrieval plus cited answers without building a parsing pipeline, and if you accept that the retrieval and agent run on data.rag.ac.cn rather than on your machine. Do not adopt it if you need offline operation, if your corpus is not on arXiv, or if you cannot send your queries to a hosted endpoint. Before committing, verify three things: that the 300 agentic calls per day covers your usage, that the section names returned by deepxiv paper --head line up with the papers you care about, and that the registered token flow works from your environment, since the agentic commands will not run without it.

## FAQ

### Is DeepXiv SDK an official Python SDK?

It is a Python package published as deepxiv-sdk that provides a CLI and a Reader class over the hosted DeepXiv service. The README describes it as a CLI and Python SDK, and setup.py lists it under the name deepxiv-sdk.

### How do I install DeepXiv SDK?

Run pip install deepxiv-sdk. The README notes that the deepxiv talent command is not on PyPI yet and ships in 1.1.0b1, so that one requires installing from the GitHub repository instead.

### Does DeepXiv SDK need an API key?

The CLI auto-registers a token on first use, but the agentic commands ask and talent need a registered key from data.rag.ac.cn/register, configured with deepxiv config --token. Every account gets 300 agentic calls per day free.

### What is the difference between deepxiv ask and deepxiv search?

ask sends a question and returns an answer cited with arXiv IDs, while search filters a result set by authors, organizations, categories, venue and citation floors. The README suggests using search once you already know what you are looking for.

### Can I read only part of a paper with DeepXiv SDK?

Yes. deepxiv paper supports --brief for a title and TLDR, --head for the section list, and --section to read a single section. The README advises taking section names from --head because papers do not share a common outline.

## Sources

- [DeepXiv/deepxiv_sdk on GitHub](https://github.com/DeepXiv/deepxiv_sdk)
- [Issues](https://github.com/DeepXiv/deepxiv_sdk/issues)
- [License: MIT](https://github.com/DeepXiv/deepxiv_sdk/blob/main/LICENSE)
- [Project website](https://data.rag.ac.cn/api/docs)
- [README](https://github.com/DeepXiv/deepxiv_sdk/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/deepxiv-deepxiv-sdk