deepxiv-sdk

The Reader class is used for programmatic access to paper content. Common tasks include:

• Searching for papers
• Retrieving paper metadata
• Reading specific sections
• Accessing paper previews and full content

DeepXiv is designed for agents to avoid loading full papers unnecessarily. It follows a "search → judge → read" workflow using specific CLI flags to access content in layers:

1. Search: Find candidate papers using deepxiv search.
2. Judge: Use --brief to get a high-level summary (Title, TLDR, keywords, citations, GitHub link).
3. Analyze Structure: Use --head to see the chapter overview and token distribution.
4. Deep Read: Use --section NAME to read only specific parts (e.g., Method, Introduction) or use --preview for a ~10k character snippet.

deepxiv search "agentic memory" --limit 5     # 1. Find candidates
deepxiv paper 2409.05591 --brief              # 2. Quick judgment
deepxiv paper 2409.05591 --head               # 3. Check structure
deepxiv paper 2409.05591 --section Method     # 4. Targeted reading

The Agent class provides high-level intelligent analysis of research papers. It supports:

• Simple queries and detailed analysis
• Follow-up questions (the agent maintains context across queries)
• Multiple LLM providers (OpenAI, DeepSeek, OpenRouter, etc.)
• Advanced research tasks like literature reviews, methodology comparisons, and trend analysis

Key Agent Methods & Tips:

• agent.reset_papers(): Use this to clear the current context and start fresh on a new topic.
• print_process=True: Enable this to see the agent's internal reasoning steps.
• stream=True: Enable this for real-time response streaming.

You can fine-tune the Agent's performance by adjusting several parameters:

• Model Selection: Change the model string (e.g., "gpt-4", "gpt-3.5-turbo", "deepseek-chat").
• LLM Parameters: Adjust temperature, max_tokens, and max_llm_calls to control creativity and cost/depth.
• Providers: Switch between different LLM providers like OpenAI, DeepSeek, or OpenRouter.

You can install the core SDK using pip. For a full-stack experience including an MCP server and a built-in research agent, install the all extra.

On first use, the CLI automatically registers a free anonymous token (1,000 requests/day) and saves it to ~/.env, so no manual setup is required before your first query.

# Standard installation
pip install deepxiv-sdk

# Full stack installation (includes MCP server + research agent)
pip install "deepxiv-sdk[all]"

For large-scale tasks, use pagination and batch loops.

Pagination: Use the offset parameter in reader.search() to iterate through results in chunks.

Example: Paginated Search

all_results = []
for offset in range(0, 500, 100):
    results = reader.search("agent memory", size=100, offset=offset)
    all_results.extend(results['results'])

# 获取前 500 个结果
all_results = []
for offset in range(0, 500, 100):
    results = reader.search(
        "agent memory",
        size=100,
        offset=offset
    )
    all_results.extend(results['results'])

print(f"总共获取论文数: {len(all_results)}")

DeepXiv resolves tokens in the following order: --token option $\rightarrow$ DEEPXIV_TOKEN environment variable $\rightarrow$ ~/.env file.

Token Types and Limits

Commands

# Automatically register (recommended for first use)
deepxiv search "agent"

# Save a token to ~/.env
deepxiv config --token YOUR_TOKEN

# Use an environment variable
export DEEPXIV_TOKEN="your_token"

# Pass token per command
deepxiv paper 2409.05591 --token YOUR_TOKEN

You can add DeepXiv to Claude Desktop as an MCP (Model Context Protocol) server. This allows Claude to use tools like search_papers, get_paper_brief, and get_full_paper directly.

Add the following configuration to your claude_desktop_config.json:

Paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "deepxiv": {
      "command": "deepxiv",
      "args": ["serve"],
      "env": {
        "DEEPXIV_TOKEN": "your_token_here"
      }
    }
  }
}

The SDK requires API tokens for DeepXiv and your chosen LLM provider.

DeepXiv Token: The deepxiv CLI auto-registers DEEPXIV_TOKEN on its first use and saves it to ~/.env. You can also set it manually as an environment variable.

LLM Provider Tokens: Set the appropriate environment variable for your provider (e.g., OPENAI_API_KEY or DEEPSEEK_API_KEY).

export DEEPXIV_TOKEN="your_deepxiv_token"
export OPENAI_API_KEY="your_openai_key"
# Or for DeepSeek:
export DEEPSEEK_API_KEY="your_deepseek_key"