DeepReviewer 2.0 Documentation

The PASA tool has migrated from a heavy, single-process model to a client-server architecture using vLLM resident inference.

Old Architecture (pasa_tool_heavy.py): The model was loaded into GPU memory every time the tool was called, resulting in high latency (60-180s) for the first call.

New Architecture (vLLM Decoupled):

1. DirectorAgent (MCP) calls a lightweight HTTP client (pasa_tool.py).
2. pasa_tool.py sends an HTTP request to the pasa_server.py (a Flask orchestration service).
3. pasa_server.py communicates with vLLM (OpenAI Server) where the crawler and selector models are permanently resident in GPU memory.

Benefits:

• Reduced Latency: Subsequent calls only incur search time (30-120s) because models are pre-loaded.
• High Concurrency: Supports multiple concurrent requests via Flask multi-threading.
• Resource Isolation: GPU management is independent of the main process, allowing for remote deployment on dedicated GPU servers.

PASA (adapted for DeepReviewer-2.0) provides a service layout consisting of two vLLM OpenAI-compatible inference services (crawler and selector) and a Flask orchestrator.

Requirements

• Linux + NVIDIA GPU
• Python 3.10+ (3.11 recommended)
• Working CUDA environment
• Network access to Hugging Face, arXiv, and Serper

Installation Steps

1. Install Dependencies: Run the following in your Python environment:

cd <repo_root>/pasa
pip install --upgrade pip
pip install \
  torch transformers \
  vllm "openai>=1.52,<1.76" \
  flask flask-cors \
  requests httpx arxiv \
  beautifulsoup4 lxml

2. Download Models: Use huggingface-cli to download the crawler and selector models to local directories:

# crawler
huggingface-cli download bytedance-research/pasa-7b-crawler --local-dir /data/models/pasa-7b-crawler

# selector
huggingface-cli download bytedance-research/pasa-7b-selector --local-dir /data/models/pasa-7b-selector

3. Prepare Data: Download the official PASA dataset (e.g., cs_paper_2nd.zip and id2paper.json) and store them locally.

4. Configure Environment: Copy the example environment file and edit it with your local paths and keys:

cd <repo_root>/pasa
cp .pasa_env.example .pasa_env.local
# Edit .pasa_env.local with your specific settings

5. Start the Server: Use the unified start script:

# Foreground (for debugging)
bash start_pasa_server.sh

# Background (for long-running use)
bash start_pasa_server.sh --background

Copy the example environment file to .env and configure the required settings for LLM, MinerU, and Paper Search providers.

LLM Configuration (OpenAI-compatible)

• BASE_URL: The base URL for your OpenAI-compatible service.
• AGENT_MODEL: The model used for reviewing (e.g., gpt-5.2).
• OPENAI_API_KEY: Your API key (required if the gateway requires authentication).
• OPENAI_AGENTS_DISABLE_TRACING: Set to 1 to reduce local gateway tracing noise.

MinerU Configuration

• MINERU_API_TOKEN: Your API token from mineru.net.

Paper Search Configuration

DeepReviewer supports two providers:

1. DeepXiv (Recommended)

Set PAPER_SEARCH_PROVIDER=deepxiv and provide:

• DEEPXIV_API_TOKEN: Your DeepXiv API token.
• DEEPXIV_API_BASE_URL: Defaults to https://data.rag.ac.cn.
• DEEPXIV_RETRIEVE_TOP_K: Number of papers to retrieve.

2. PASA (Advanced/Local)

Set PAPER_SEARCH_PROVIDER=pasa and provide:

• PAPER_SEARCH_BASE_URL: The URL of your local PASA service.
• PAPER_SEARCH_ENDPOINT: The search endpoint (e.g., /pasa/search).
• PAPER_SEARCH_HEALTH_ENDPOINT: The health check endpoint.

cp .env.example .env

DeepXiv is the recommended path for the simplest setup as it does not require a local PASA model service. To use it, you must provide a DeepXiv API token and configure the following environment variables in your .env file.

Startup Behavior:

• DeepReviewer performs a health check via GET {DEEPXIV_API_BASE_URL}/stats/usage.
• If the token is missing, the tool returns status=not_started with availability=missing_api_token.
• If the health check fails, it returns status=not_started with availability=health_check_failed.

Search Behavior:

• The tool supports question_list (up to 3 distinct questions), which are merged into a single deduplicated result list.
• Results are normalized to include: title, abstract, arxiv_id, url, abs_url, pdf_url, authors, categories, citation_count, and provider=deepxiv.

PAPER_SEARCH_ENABLED=true
PAPER_SEARCH_PROVIDER=deepxiv

DEEPXIV_API_BASE_URL=https://data.rag.ac.cn
DEEPXIV_API_TOKEN=your_deepxiv_token
DEEPXIV_REQUEST_TIMEOUT_SECONDS=60
DEEPXIV_RETRIEVE_TOP_K=8
DEEPXIV_DEFAULT_SOURCE=arxiv

Use the PASA path if you intend to run the PASA model service locally. This requires installing PASA extras and running the PASA server separately.

Setup Steps:

1. Install PASA extras: pip install -e ".[pasa]".
2. Configure the PASA environment by copying pasa/.pasa_env.example to pasa/.pasa_env and editing model paths, ports, GPU selection, Serper token, and proxy settings.
3. Start the server: cd pasa && bash start_pasa_server.sh --background.
4. Configure DeepReviewer environment variables to point to your local service.

Startup Behavior:

• DeepReviewer checks health via GET {PAPER_SEARCH_BASE_URL}{PAPER_SEARCH_HEALTH_ENDPOINT}.
• If the health check fails, the tool returns status=not_started and the review proceeds in Retrieval-Disabled Mode.

Search Behavior:

• The tool sends a POST request to {PAPER_SEARCH_BASE_URL}{PAPER_SEARCH_ENDPOINT} with a JSON payload containing query and question_list.

# 1. Install extras
pip install -e ".[pasa]"

# 2. Configure PASA environment
cp pasa/.pasa_env.example pasa/.pasa_env

# 3. Start PASA server
cd pasa
bash start_pasa_server.sh --background

# 4. Configure DeepReviewer
PAPER_SEARCH_ENABLED=true
PAPER_SEARCH_PROVIDER=pasa
PAPER_SEARCH_BASE_URL=http://127.0.0.1:8001
PAPER_SEARCH_API_KEY=
PAPER_SEARCH_ENDPOINT=/pasa/search
PAPER_SEARCH_TIMEOUT_SECONDS=120
PAPER_SEARCH_HEALTH_ENDPOINT=/health
PAPER_SEARCH_HEALTH_TIMEOUT_SECONDS=5

To run the PASA service locally, follow these steps:

1. Install Dependencies: Ensure you are in a Python 3.10+ environment with an NVIDIA GPU and CUDA installed. Run:

   cd <repo_root>/pasa
   pip install --upgrade pip
   pip install torch transformers vllm "openai>=1.52,<1.76" flask flask-cors requests httpx arxiv beautifulsoup4 lxml

2. Download Models: Use huggingface-cli to download the required models:

   # crawler
   huggingface-cli download bytedance-research/pasa-7b-crawler --local-dir /data/models/pasa-7b-crawler
   
   # selector
   huggingface-cli download bytedance-research/pasa-7b-selector --local-dir /data/models/pasa-7b-selector

3. Prepare Paper Database: Download the required paper DB files (e.g., cs_paper_2nd.zip and id2paper.json) and place them in a local directory.
4. Configure Environment: Copy the example environment file and edit it with your local paths and API keys:

   cd <repo_root>/pasa
   cp .pasa_env.example .pasa_env.local
   vim .pasa_env.local

cd <repo_root>/pasa
pip install --upgrade pip
pip install \
  torch transformers \
  vllm "openai>=1.52,<1.76" \
  flask flask-cors \
  requests httpx arxiv \
  beautifulsoup4 lxml