### Quick Start Agent Initialization

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/agent.md

Initialize the Agent with a token and API key for basic usage. This example shows how to perform a simple query.

```python
from deepxiv_sdk import Reader, Agent

reader = Reader(token="your_token")
agent = Agent(api_key="sk-ப்படாத", reader=reader)
answer = agent.query("What are transformers?")
print(answer)
```

--------------------------------

### Run DeepXIV SDK Examples

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/examples/README.md

Execute the provided example scripts to see the deepxiv-sdk in action.

```bash
python examples/quickstart.py
python examples/example_reader.py
python examples/example_agent.py
python examples/example_advanced.py
```

--------------------------------

### Install DeepXiv SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Install the deepxiv-sdk package using pip. This is the first step to start using the tool.

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

--------------------------------

### Install DeepXiv SDK with All Features

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Install the deepxiv-sdk with all optional dependencies, including the full stack for MCP server and research agent.

```bash
pip install "deepxiv-sdk[all]"
```

--------------------------------

### Install DeepXiv SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Install the DeepXiv SDK with different feature sets using pip.

```bash
# Basic SDK (reader only)
pip install deepxiv-sdk

# With MCP server
pip install "deepxiv-sdk[mcp]"

# With agent support
pip install "deepxiv-sdk[agent]"

# Everything
pip install "deepxiv-sdk[all]"
```

--------------------------------

### Install DeepXIV SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/examples/README.md

Install the deepxiv-sdk package with all optional dependencies using pip.

```bash
pip install deepxiv-sdk[all]
```

--------------------------------

### Example Prompt for Claude

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/mcp-server.md

An example prompt demonstrating how Claude can utilize MCP server tools to search for papers and retrieve summaries.

```text
Search for papers about agent memory and give me a summary of the 
top 3 results, including their brief information and key findings.
```

--------------------------------

### DeepXIV CLI Examples

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/README.md

Demonstrates common DeepXIV CLI commands for searching, reading papers, and querying the agent.

```bash
deepxiv search "diffusion" --limit 5
deepxiv paper 2409.05591 --brief
deepxiv agent query "What's new in vision transformers?"
```

--------------------------------

### Get Command Help

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Use the --help flag with any deepxiv command to get detailed usage information and available options.

```bash
deepxiv <command> --help
```

--------------------------------

### Initialize and Query DeepXIV Agent with Python

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Initialize the Agent class with API credentials and then use it to query for research topics. Ensure you have installed the SDK with 'pip install "deepxiv-sdk[all]"'.

```python
from deepxiv_sdk import Agent

agent = Agent(api_key="your_key", base_url="https://api.deepseek.com/v1", model="deepseek-chat")
print(agent.query("Compare key ideas in transformers and attention mechanisms"))
```

--------------------------------

### Install CLI Skill

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Create a directory for skills and create a symbolic link to the deepxiv-cli skill.

```bash
mkdir -p $CODEX_HOME/skills
ln -s "$(pwd)/skills/deepxiv-cli" $CODEX_HOME/skills/deepxiv-cli
```

--------------------------------

### Project Setup: requirements.txt

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

List of Python dependencies required for the project. Ensure `deepxiv-sdk` is version 0.3.0 or higher.

```text
deepxiv-sdk>=0.3.0
python-dotenv
```

--------------------------------

### Example Usage of Agent and PaperInfo

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/types.md

Demonstrates how to add a paper to the agent, retrieve loaded papers, and iterate through the PaperInfo to print titles, categories, and section token counts. This example showcases the practical application of the PaperInfo type.

```python
from deepxiv_sdk import Agent, Reader

reader = Reader(token="your_token")
agent = Agent(api_key="sk-...", reader=reader)

agent.add_paper("2409.05591")
papers = agent.get_loaded_papers()

for arxiv_id, paper_info in papers.items():
    print(f"Title: {paper_info['title']}")
    print(f"Categories: {', '.join(paper_info['categories'])}")
    for section_name, section_info in paper_info['sections'].items():
        print(f"  {section_name}: {section_info.get('token_count', 0)} tokens")
```

--------------------------------

### Project Setup: .env file

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Environment variables file for storing API keys and tokens. Replace placeholder values with your actual credentials.

```bash
DEEPXIV_TOKEN=sk-deepxiv-xxxxx
OPENAI_API_KEY=sk-proj-xxxxx
DEEPSEEK_API_KEY=sk-xxxxx
```

--------------------------------

### Project Setup: main.py

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Main Python script demonstrating how to initialize the DeepXIV SDK and use the Agent to query information. It loads environment variables for authentication.

```python
import os
from dotenv import load_dotenv
from deepxiv_sdk import Reader, Agent

load_dotenv()

reader = Reader(token=os.getenv("DEEPXIV_TOKEN"))
agent = Agent(
    api_key=os.getenv("OPENAI_API_KEY"),
    reader=reader
)

answer = agent.query("What's new in agent memory?")
print(answer)
```

--------------------------------

### Get Paper Preview

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Use the CLI to get a preview of a paper (approximately 10k characters) by its arXiv ID.

```bash
deepxiv paper 2409.05591 --preview
```

--------------------------------

### Piping to Other Tools

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of piping JSON output to jq for filtering.

```bash
deepxiv search "topic" --format json | jq '.results[] | .arxiv_id'
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/configuration.md

Set up environment variables for DeepXIV token and LLM API keys in a .env file. This file can be placed in the home directory or the project directory.

```bash
# DeepXiv token
DEEPXIV_TOKEN=sk-deepxiv-xxxxx

# LLM API keys
OPENAI_API_KEY=sk-proj-xxxxx
DEEPSEEK_API_KEY=sk-xxxxx
OPENROUTER_API_KEY=sk-or-xxxxx

# Custom configuration
DEBUG=false
LOG_LEVEL=info
```

--------------------------------

### Minimal Digest Workflow Example

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-trending-digest/SKILL.md

A complete sequence of commands for generating a small-scale paper digest.

```bash
deepxiv trending --days 7 --limit 5 --json
deepxiv paper 2603.20639 --brief
deepxiv paper 2603.26221 --brief
deepxiv paper 2603.20639 --head
deepxiv paper 2603.20639 --section Introduction
```

--------------------------------

### Troubleshooting Agent Dependencies

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Command to install missing dependencies for agent functionality.

```bash
pip install deepxiv-sdk[agent]
```

--------------------------------

### Get Quick Summary of a Paper

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Use the CLI to get a brief summary of a paper using its arXiv ID.

```bash
deepxiv paper 2409.05591 --brief
```

--------------------------------

### Custom Token Configuration

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of configuring the Reader class with a custom token and timeout.

```python
from deepxiv_sdk import Reader
reader = Reader(token="YOUR_TOKEN", timeout=120, max_retries=5)
```

--------------------------------

### Start DeepXIV MCP Server

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/cli.md

Launches the MCP server for integration with clients like Claude Desktop. Configure server details in `claude_desktop_config.json`.

```bash
deepxiv serve
```

--------------------------------

### CLI Commands for DeepXiv SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/INDEX.md

Provides examples of using the DeepXiv SDK command-line interface for searching papers, retrieving specific content, and performing agent queries.

```bash
# Search
deepxiv search "transformer" --limit 10

# Read
deepxiv paper 2409.05591 --brief
deepxiv paper 2409.05591 --section Introduction

# Trending
deepxiv trending --days 7 --limit 10

# Intelligent queries
deepxiv agent query "What's new in agent memory?" --verbose
```

--------------------------------

### Example Search Query and Result Processing

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/types.md

Demonstrates how to perform a search and process the results, checking the status and iterating through the papers to print details.

```python
from deepxiv_sdk import Reader

reader = Reader()
results = reader.search("transformer", size=5)

if results["status"] == "success":
    print(f"Total: {results['total_count']}")
    for paper in results["result"]:
        print(f"{paper['arxiv_id']}: {paper['title']}")
        print(f"  Score: {paper['score']:.3f}, Citations: {paper['citation_count']}")
```

--------------------------------

### Quick Paper Review Workflow

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

A common workflow to quickly review a paper using the DeepXiv CLI, starting with fetching brief information.

```bash
# Step 1: Get brief info
deepxiv paper 2409.05591 --brief
```

--------------------------------

### Troubleshooting Daily Limit Exceeded

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of an error when the daily request limit is reached.

```bash
deepxiv search "topic"
# Error: RateLimitError: Daily limit reached
```

--------------------------------

### Set API Tokens for DeepXIV SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/examples/README.md

Set your API tokens as environment variables before running the examples. The DEEPXIV_TOKEN is auto-registered on first use.

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

--------------------------------

### Initialize Reader and Perform Paper Search and Retrieval

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/INDEX.md

Demonstrates initializing the Reader class and performing various paper retrieval operations like searching, getting brief summaries, paper heads, specific sections, and raw content.

```python
from deepxiv_sdk import Reader

reader = Reader()  # Auto-creates token on first use

# Search
results = reader.search("agent memory", size=10)

# Read
brief = reader.brief("2409.05591")
sections = reader.head("2409.05591")
content = reader.section("2409.05591", "Method")
full = reader.raw("2409.05591")
```

--------------------------------

### Implement Search Pagination

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Fetches search results in chunks using the `offset` and `size` parameters to retrieve a large number of papers. This example retrieves up to 500 results in batches of 100.

```python
# Get first 500 results
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"Total papers fetched: {len(all_results)}")
```

--------------------------------

### Set Agent LLM Configuration via Environment Variables

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Configures the API key, base URL, and model for the agent using environment variables. This allows flexible LLM setup without modifying code.

```bash
# LLM API keys (for agent)
export DEEPXIV_AGENT_API_KEY="your_api_key"
export DEEPXIV_AGENT_BASE_URL="https://api.example.com"
export DEEPXIV_AGENT_MODEL="gpt-4"
```

--------------------------------

### Initialize Reader and Agent, Perform Search and Read

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/INDEX.md

Demonstrates how to initialize the Reader and Agent classes, perform a paper search, and retrieve brief summaries or specific sections of papers.

```python
from deepxiv_sdk import Reader, Agent

# Search and read papers
reader = Reader(token="your_token")
results = reader.search("transformers", size=5)
brief = reader.brief(results["result"][0]["arxiv_id"])
intro = reader.section(results["result"][0]["arxiv_id"], "Introduction")
```

--------------------------------

### Intelligent Agent with DeepXiv CLI

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Use `deepxiv agent` for advanced analysis. `query` performs a one-time analysis, while `--max-turn` and `--verbose` enable multi-turn reasoning. `config` is used for LLM setup.

```bash
deepxiv agent query "What are key innovations in this paper?"
```

```bash
deepxiv agent query "Compare these two approaches" --max-turn 10 --verbose
```

```bash
deepxiv agent config
```

--------------------------------

### Get Trending Papers and Social Impact with Reader API

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/README.md

Retrieve a list of trending papers within a specified period and get social impact metrics for a specific paper.

```python
# Trending & social signals
trending = reader.trending(days=7)
impact = reader.social_impact("2409.05591")
```

--------------------------------

### Get Full Paper Content (arXiv)

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/reader.md

Fetches the complete arXiv paper content in markdown format, including all sections and metadata. Use this to get the entire paper as a single markdown string.

```python
full_paper = reader.raw("2409.05591")
with open("paper.md", "w") as f:
    f.write(full_paper)
```

--------------------------------

### Initialize Reader and Agent for Intelligent Reasoning

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/INDEX.md

Shows how to set up the Reader and Agent for multi-turn reasoning, including performing single queries, multi-turn conversations, and manually loading papers for analysis.

```python
from deepxiv_sdk import Reader, Agent

reader = Reader(token="your_token")
agent = Agent(api_key="sk-...", reader=reader, model="gpt-4")

# Single query
answer = agent.query("What are the latest papers about agent memory?")

# Multi-turn (papers persist)
agent.query("Find papers on transformers.")
agent.query("How do these compare on efficiency?")

# Manual paper loading
agent.add_paper("2409.05591")
agent.query("Explain the methodology in this paper.")
```

--------------------------------

### Initialize Agent with Custom Provider and Extra Options

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/agent.md

Configure the Agent for a custom provider, including a local base URL and additional provider-specific options via `extra_body`.

```python
from deepxiv_sdk import Reader, Agent

# Initialize reader
reader = Reader(token="your_token")

# Custom provider with extra options
agent = Agent(
    api_key="key",
    reader=reader,
    base_url="http://localhost:8000/v1",
    model="local-model",
    extra_body={"temperature_override": 0.5},
)
```

--------------------------------

### Search Result Format

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of the output format for search results.

```text
1. Title of Paper (2409.05591)
   - Field: Computer Science / AI
   - Citations: 150
   - Key idea: Brief 1-line summary of main contribution
```

--------------------------------

### Troubleshooting Timeout

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of a timeout error when processing large papers.

```bash
deepxiv paper <large_paper_id>
# Error: Request timed out
```

--------------------------------

### Configure DeepXiv Token via CLI

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Set up the DeepXiv SDK token using the CLI for automatic registration, manual configuration, or per-command usage.

```bash
# First CLI command auto-registers and saves token to ~/.env
deepxiv search "transformer"

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

# Or use environment variable
export DEEPXIV_TOKEN="your_token"

# Or pass per-command
deepxiv search "transformer" --token YOUR_TOKEN
```

--------------------------------

### Initialize Agent for Queries with Python SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Set up an Agent for querying research papers, supporting different LLM providers like OpenAI and DeepSeek. Requires API keys and a Reader instance.

```python
from deepxiv_sdk import Reader, Agent
import os

reader = Reader(token=os.getenv("DEEPXIV_TOKEN"))

# OpenAI
agent = Agent(
    api_key=os.getenv("OPENAI_API_KEY"),
    reader=reader,
    model="gpt-4"
)

answer = agent.query("What are the latest papers about agent memory?")
print(answer)

# DeepSeek
agent = Agent(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    reader=reader,
    model="deepseek-chat",
    base_url="https://api.deepseek.com/v1"
)
```

--------------------------------

### Troubleshooting Token Invalid

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of an error when the authentication token is invalid or expired.

```bash
deepxiv paper 2409.05591
# Error: AuthenticationError: Invalid or expired token
```

--------------------------------

### Troubleshooting Paper Not Found

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of an error when an invalid arXiv ID is provided.

```bash
deepxiv paper invalid_id
# Error: NotFoundError: Paper not found
```

--------------------------------

### Initialize DeepXIV Agent with Constructor Options

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/configuration.md

Instantiate the Agent class, providing an API key, a configured Reader instance, and various LLM parameters like model, base URL, and token limits. Essential for setting up the agent's core functionality.

```python
from deepxiv_sdk import Agent, Reader

reader = Reader(token="your_token")

agent = Agent(
    api_key="sk-ாலத்தில்",
    reader=reader,
    model="gpt-4",
    base_url=None,
    max_llm_calls=20,
    max_time_seconds=600,
    max_tokens=4096,
    temperature=0.7,
    print_process=False,
    stream=False,
    max_consecutive_failures=3,
    extra_body=None,
    enable_thinking=None
)
```

--------------------------------

### raw

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/reader.md

Get the complete paper in markdown format, including all sections and metadata.

```APIDOC
## raw

### Description
Get the complete paper in markdown format. Includes all sections and metadata.

### Method
```python
def raw(self, arxiv_id: str) -> str
```

### Parameters
#### Path Parameters
- **arxiv_id** (str) - Yes - arXiv ID

### Returns
`str` — Full paper markdown

### Raises
`APIError` — Request fails

### Example
```python
full_paper = reader.raw("2409.05591")
with open("paper.md", "w") as f:
    f.write(full_paper)
```
```

--------------------------------

### Configure Agent with Local Ollama LLM

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Initialize the Agent to use a locally hosted LLM via Ollama. A dummy API key is sufficient for local connections.

```python
# Local Ollama
agent = Agent(
    api_key="ollama",  # dummy key
    base_url="http://localhost:11434/v1",
    model="llama2"
)
```

--------------------------------

### Batch Processing Papers

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of iterating through multiple paper IDs to retrieve summaries.

```bash
for id in 2409.05591 2504.21776 2503.04975; do
    echo "=== $id ==="
    deepxiv paper $id --brief
done
```

--------------------------------

### Paper Reading Output Format

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Example of the output format for paper reading commands.

```text
From `deepxiv paper 2409.05591 --brief`:
- Title: MemGPT: Towards LLMs as Operating Systems
- TLDR: Introduces hierarchical memory management for extended context
- Key concepts: agent memory, context management, LLM systems
- (~500 tokens)
```

--------------------------------

### Pagination and Reranking

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Demonstrates how to paginate search results using --offset and enable fine reranking with --use-fine-rerank.

```bash
deepxiv search "LLM alignment" --limit 10 --offset 10        # page 2
```

```bash
deepxiv search "transformer model" --use-fine-rerank --limit 10   # opt-in fine rerank (off by default)
```

--------------------------------

### preview

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/reader.md

Get a truncated preview of the paper (approximately 10,000 characters), suitable for mobile or quick scanning.

```APIDOC
## preview

### Description
Get a truncated preview (~10,000 characters) of the paper. Useful for mobile or quick scanning.

### Method
```python
def preview(self, arxiv_id: str) -> Dict[str, Any]
```

### Parameters
#### Path Parameters
- **arxiv_id** (str) - Yes - arXiv ID

### Returns
`Dict[str, Any]`

Contains: `content` (truncated), `is_truncated`, `total_characters`

### Raises
`APIError` — Request fails

### Example
```python
preview = reader.preview("2409.05591")
print(preview["content"])
print(f"Full paper is {preview['total_characters']} characters")
```
```

--------------------------------

### reset_papers

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/agent.md

Clears all loaded papers from the agent's context, which is useful for starting a new topic or analysis.

```APIDOC
## reset_papers

### Description
Clear all loaded papers from the agent's context. Useful when switching topics.

### Method
`reset_papers(self)`

### Returns
- None

### Example
```python
agent.reset_papers()
agent.query("Start a new topic...")
```
```

--------------------------------

### Reset Agent Conversation

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Resets the agent to start a new conversation. Call this before initiating a new dialogue.

```python
agent.reset_papers()
```

--------------------------------

### Progressive Reading Workflow

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Demonstrates the progressive reading workflow using the deepxiv CLI. This allows agents to decide on reading value before loading full papers.

```bash
deepxiv search "agentic memory" --limit 5     # 1. find candidates
```

```bash
deepxiv paper 2409.05591 --brief              # 2. decide if it's worth reading
```

```bash
deepxiv paper 2409.05591 --head               # 3. inspect structure & token distribution
```

```bash
deepxiv paper 2409.05591 --section Method     # 4. read only the valuable parts
```

--------------------------------

### Initialize DeepXIV Reader with Constructor Options

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/configuration.md

Instantiate the Reader class with explicit API token, base URL, timeout, and retry settings. Useful for direct control over SDK behavior.

```python
from deepxiv_sdk import Reader

reader = Reader(
    token="your_api_token",
    base_url="https://data.rag.ac.cn",
    timeout=60,
    max_retries=3,
    retry_delay=1.0
)
```

--------------------------------

### Manage DeepXIV Tokens

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Demonstrates various ways to manage DeepXIV API tokens, including auto-registration, saving to a config file, using environment variables, and passing tokens per command.

```bash
deepxiv search "agent"                          # auto-register on first use (recommended)
deepxiv config --token YOUR_TOKEN               # save to ~/.env
export DEEPXIV_TOKEN="your_token"               # or use an env var
deepxiv paper 2409.05591 --token YOUR_TOKEN     # or pass per command
```

--------------------------------

### Import ToolExecutor and get_tools_definition

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/modules.md

Imports the ToolExecutor class for executing agent tools and the function to get tool definitions.

```python
from deepxiv_sdk.agent.tools import ToolExecutor, get_tools_definition
```

--------------------------------

### Get Semantic Scholar Metadata

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Use the CLI to fetch metadata for a paper using its Semantic Scholar ID.

```bash
deepxiv sc 258001
```

--------------------------------

### Get Trending Papers

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Use the CLI to fetch trending papers within a specified number of days and a limit.

```bash
deepxiv trending --days 7 --limit 10
```

--------------------------------

### Initialize Agent with OpenRouter API

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/agent.md

Set up the Agent to connect to OpenRouter, specifying a model and the API base URL.

```python
from deepxiv_sdk import Reader, Agent

# Initialize reader
reader = Reader(token="your_token")

# OpenRouter
agent = Agent(
    api_key="sk-or-...",
    reader=reader,
    model="anthropic/claude-3-opus",
    base_url="https://openrouter.ai/api/v1",
)
```

--------------------------------

### Initialize Agent with OpenAI (Default)

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/agent.md

Initialize the Agent for use with OpenAI's API, enabling process printing.

```python
from deepxiv_sdk import Reader, Agent

# Initialize reader
reader = Reader(token="your_token")

# OpenAI (default)
agent = Agent(
    api_key="sk-...",
    reader=reader,
    model="gpt-4",
    print_process=True,
)
```

--------------------------------

### Search Between Dates

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Searches for papers within a date range. Pass the start and end dates to --date-str.

```bash
deepxiv search "image generation" \
  --date-search-type between --date-str 2025-06-01 --date-str 2025-07-01 --limit 5
```

--------------------------------

### Initialize Reader with Token in Python

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Instantiate the Reader class and pass the authentication token directly in the Python code.

```python
from deepxiv_sdk import Reader

reader = Reader(token="your_token")
```

--------------------------------

### CLI Paper Not Found Error Example

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/errors.md

Shows the error message from the DeepXIV CLI when a requested paper ID does not exist.

```bash
$ deepxiv paper 9999.99999
❌ 纸张未找到。 / Paper not found.
```

--------------------------------

### Quick Assessment Workflow

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Commands for a rapid assessment of a paper by reading specific sections.

```bash
deepxiv paper 2409.05591 --section Introduction

deepxiv paper 2409.05591 --section Results
```

--------------------------------

### Configure Agent with DeepXIV SDK

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/INDEX.md

Instantiate an Agent object with API key, reader, and tuning parameters for LLM calls. Adjust max_llm_calls, max_time_seconds, max_tokens, and temperature for deeper reasoning and performance.

```python
agent = Agent(
    api_key="sk-…",
    reader=reader,
    max_llm_calls=50,        # Deeper reasoning
    max_time_seconds=1800,   # 30 minutes
    max_tokens=8192,
    temperature=0.5,
)
```

--------------------------------

### Web Search

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/README.md

Performs a web search for a given query. Use --json to get results in JSON format.

```bash
deepxiv wsearch "karpathy"
```

```bash
deepxiv wsearch "karpathy" --json
```

--------------------------------

### Configure Agent with DeepSeek LLM

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Initialize the Agent with DeepSeek LLM credentials and endpoint. Ensure your API key and base URL are correctly set.

```python
# DeepSeek
agent = Agent(
    api_key="your_deepseek_key",
    base_url="https://api.deepseek.com/v1",
    model="deepseek-chat"
)
```

--------------------------------

### Read Papers via CLI

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/README.md

Retrieve papers using the CLI, with options to get a brief summary or a specific section.

```bash
# Read
deepxiv paper 2409.05591 --brief
deepxiv paper 2409.05591 --section Introduction
```

--------------------------------

### Get Full PMC Paper

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/mcp-server.md

Retrieves the complete PMC paper in JSON format. The output is a stringified JSON object.

```python
def get_pmc_full(pmc_id: str) -> str:
    """Get the complete PMC paper in JSON format."""
    pass
```

--------------------------------

### DeepXIV CLI Rate Limit Error Example

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/cli.md

Shows the error message when the API token has reached its daily usage limit.

```bash
❌ 当前 token 已到日使用上限。 / Your token has reached its daily usage limit.
   请访问 https://data.rag.ac.cn/register 注册，以获得更高 limit。
```

--------------------------------

### Query Agent via CLI

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/README.md

Interact with the intelligent agent through the CLI to ask questions and get answers, with an option for verbose output.

```bash
# Agent
deepxiv agent query "What's new in AI?" --verbose
```

--------------------------------

### Configure Agent for OpenAI API

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/configuration.md

Set up the Agent to use the OpenAI API by providing the OpenAI API key and specifying the model. Leverages environment variables for secure key management.

```python
import os
from deepxiv_sdk import Agent, Reader

reader = Reader(token=os.getenv("DEEPXIV_TOKEN"))
agent = Agent(
    api_key=os.getenv("OPENAI_API_KEY"),
    reader=reader,
    model="gpt-4",
)
```

--------------------------------

### Get Trending Papers via CLI

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/README.md

Fetch trending papers for a specified number of past days using the command-line interface.

```bash
# Trending
deepxiv trending --days 7
```

--------------------------------

### Get PMC Biomedical Paper Metadata

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/quick-start.md

Use the CLI to fetch metadata for a PMC biomedical paper using its PMC ID.

```bash
deepxiv pmc PMC544940 --head
```

--------------------------------

### Load Paper Metadata with `brief()`

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Retrieves essential paper information like title, TLDR, keywords, citations, and GitHub URL. This method is very efficient, costing minimal tokens.

```python
brief = reader.brief("2409.05591")
print(f"Title: {brief['title']}")
print(f"TLDR: {brief.get('tldr')}")
print(f"Keywords: {brief.get('keywords')}")
print(f"Citations: {brief.get('citations')}")
print(f"GitHub: {brief.get('github_url')}")
```

--------------------------------

### Perform Basic Agent Query

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/USAGE.md

Initializes an `Agent` with an OpenAI API key and model, then sends a query to the agent for complex analysis. The agent uses the provided API key for processing.

```python
from deepxiv_sdk import Agent

agent = Agent(
    api_key="your_openai_key",
    model="gpt-4"
)

answer = agent.query("What are key innovations in recent transformer papers?")
print(answer)
```

--------------------------------

### DeepXIV CLI Authentication Error Example

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/cli.md

Illustrates the error message for an invalid or missing API token, returning a 401 Unauthorized status.

```bash
# Authentication error
$ deepxiv search "transformer" --token invalid
❌ 认证失败（401 Unauthorized） / Authentication failed (401 Unauthorized)
   当前 API token 缺失或无效。 / Your API token is missing or invalid.
```

--------------------------------

### pmc_head

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/reader.md

Get metadata for a PubMed Central (PMC) paper, including title, abstract, authors, medical subject categories, and publication date.

```APIDOC
## pmc_head

### Description
Get PMC paper metadata. Returns title, abstract, authors, medical subject categories, and publication date.

### Method
```python
def pmc_head(self, pmc_id: str) -> Dict[str, Any]
```

### Parameters
#### Path Parameters
- **pmc_id** (str) - Yes - PMC ID (e.g., `"PMC544940"`, `"PMC514704"`)

### Returns
`Dict[str, Any]`

Contains: `pmc_id`, `title`, `doi`, `abstract`, `authors`, `categories`, `publish_at`

### Raises
`APIError` — Request fails

### Example
```python
pmc = reader.pmc_head("PMC544940")
print(f"Title: {pmc['title']}")
print(f"DOI: {pmc.get('doi', 'N/A')}")
```
```

--------------------------------

### Initialize Agent with Custom Provider

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/configuration.md

Configure an Agent instance to use a custom API provider by specifying the base URL and any additional parameters required by the provider.

```python
agent = Agent(
    api_key="your_key",
    reader=reader,
    model="your-model",
    base_url="https://api.provider.com/v1",
    extra_body={"custom_param": "value"},
)
```

--------------------------------

### brief

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/reader.md

Get a concise summary of a paper, including title, TLDR, keywords, citation count, publication date, and GitHub URL if available.

```APIDOC
## brief

### Description
Get concise paper summary for quick overview. Returns title, TLDR, keywords, citation count, publication date, and GitHub URL when available.

### Method
```python
def brief(self, arxiv_id: str) -> Dict[str, Any]
```

### Parameters
#### Path Parameters
- **arxiv_id** (str) - Yes - arXiv ID (e.g., `"2409.05591"`, `"2504.21776"`)

### Returns
`Dict[str, Any]`

Contains: `arxiv_id`, `title`, `tldr`, `keywords`, `publish_at`, `citations`, `src_url`, `github_url`

### Raises
`APIError` — Request fails

### Example
```python
brief = reader.brief("2409.05591")
print(f"Title: {brief['title']}")
print(f"TLDR: {brief['tldr']}")
print(f"GitHub: {brief.get('github_url', 'N/A')}")
```
```

--------------------------------

### Import create_react_graph and create_initial_state

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/modules.md

Imports functions for creating the LangGraph ReAct reasoning graph and the initial state for a query.

```python
from deepxiv_sdk.agent.graph import create_react_graph, create_initial_state
```

--------------------------------

### Get PMC Metadata

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/mcp-server.md

Retrieves metadata for a PubMed Central paper, including title, DOI, authors, abstract, categories, and publication date.

```python
def get_pmc_metadata(pmc_id: str) -> str:
    """Get PubMed Central paper metadata."""
    pass
```

--------------------------------

### Create Agent from Environment Variables

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/integration-patterns.md

Dynamically creates an Agent instance by detecting provider API keys and configurations from environment variables. Supports Deepseek, OpenRouter, and OpenAI providers.

```python
import os
from deepxiv_sdk import Reader, Agent

def create_agent_from_env() -> Agent:
    reader = Reader(token=os.getenv("DEEPXIV_TOKEN"))
    
    # Detect provider from environment
    if os.getenv("DEEPSEEK_API_KEY"):
        return Agent(
            api_key=os.getenv("DEEPSEEK_API_KEY"),
            reader=reader,
            model="deepseek-chat",
            base_url="https://api.deepseek.com/v1",
        )
    elif os.getenv("OPENROUTER_API_KEY"):
        return Agent(
            api_key=os.getenv("OPENROUTER_API_KEY"),
            reader=reader,
            model="anthropic/claude-3-opus",
            base_url="https://openrouter.ai/api/v1",
        )
    else:
        return Agent(
            api_key=os.getenv("OPENAI_API_KEY"),
            reader=reader,
            model="gpt-4",
        )

agent = create_agent_from_env()
```

--------------------------------

### Get Paper Preview

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/mcp-server.md

Retrieves a preview of the paper, approximately 10,000 characters long. This is useful for quick scanning when the full text is not required.

```python
def get_paper_preview(arxiv_id: str) -> str:
    """Get a preview (~10,000 characters) of the paper."""
    pass
```

--------------------------------

### Initialize Agent with DeepSeek API

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/_autodocs/api-reference/agent.md

Configure the Agent to use the DeepSeek API by specifying the model and base URL.

```python
from deepxiv_sdk import Reader, Agent

# Initialize reader
reader = Reader(token="your_token")

# DeepSeek
agent = Agent(
    api_key="sk-...",
    reader=reader,
    model="deepseek-chat",
    base_url="https://api.deepseek.com/v1",
)
```

--------------------------------

### Read arXiv Papers with DeepXiv CLI

Source: https://github.com/deepxiv/deepxiv_sdk/blob/main/skills/deepxiv-cli/SKILL.md

Use `deepxiv paper <id>` to access papers. Options include `--brief` for a quick summary, `--head` for structure, `--preview` for a text snippet, `--section <name>` for specific content, or no flag for the full paper.

```bash
deepxiv paper 2409.05591 --brief
```

```bash
deepxiv paper 2409.05591 --head
```

```bash
deepxiv paper 2409.05591 --preview
```

```bash
deepxiv paper 2409.05591 --section Introduction
```

```bash
deepxiv paper 2409.05591
```

```bash
deepxiv paper 2409.05591 --raw
```