DeepXiv SDK

Use this repo skill when a task needs DeepXiv's hosted literature service or its optional local research agent. It teaches a later Researcher how to choose between the Python SDK and CLI, preserve citations and evidence strength, and avoid credential, quota, truncation, and stale-API mistakes.

Start here

1. Confirm the installed package and CLI are the expected 1.0.x surface: python -c "import deepxiv_sdk; print(deepxiv_sdk.__version__)" and deepxiv --help. If the executable lists an older command set, repair the installation before using route-specific flags.
2. Install the base package with python -m pip install deepxiv-sdk. For the optional local OpenAI-compatible LangGraph agent use python -m pip install "deepxiv-sdk[agent]" (or [all]) and install tiktoken separately if the optional-import probe reports it missing.
3. Keep DeepXiv and model-provider credentials outside prompts, source files, logs, and commits. Ordinary retrieval uses a DeepXiv token; hosted ask requires a registered account key and has a separate agentic quota.
4. Run the no-network installation check before diagnosing package or optional-dependency problems.

Route by task

• Python literature research: Read reader-and-paper-research for Reader, hosted agentic search, source/citation handling, progressive reading, biomedical sources, PMC, and trending signals.
• Shell commands and operations: Read cli-and-operations for command selection, flag partitions, JSON/text output, stdout/stderr, token setup, health/debug, and CLI recovery.
• Local model-driven research loop: Read optional-local-agent for the optional Agent, LangGraph tools, provider options, persistent paper context, budgets, and circuit-breaker behavior.

Shared operating rules

• Prefer the narrowest evidence operation: search or brief first, then head, one or two sections, or preview; avoid raw/json for routine screening.
• Hosted agent_search and agent_search_stream distinguish arXiv and web flags. Preserve arXiv IDs or URLs, separate retrieved sources from sources cited in the answer, and reject answer_truncated or streamed error output as complete evidence.
• The SDK retries ordinary GET timeouts/connections with exponential backoff, but hosted agentic calls deliberately do not auto-retry because each call can spend quota. Correct the query or wait rather than hammering the endpoint.
• Network, registered credentials, remote LLM keys, and live service results are runtime prerequisites; this skill does not claim them from import or help checks. Read cross-cutting troubleshooting and the provenance baseline when a mismatch or stale checkout is suspected.