### Start PASA Server

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Execute the start script to launch the PASA server. Use the --background flag for daemonized execution or --stop/--restart for process management.

```bash
cd <repo_root>/pasa
bash start_pasa_server.sh

# Background
bash start_pasa_server.sh --background

# Stop
bash start_pasa_server.sh --stop

# Restart
bash start_pasa_server.sh --restart
```

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

### Environment Variables Setup

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Configure DeepReviewer 2.0 by copying the example `.env` file and modifying it with your specific settings for LLM providers, MinerU PDF parsing, and external paper search services.

```bash
cp .env.example .env
```

```dotenv
==================== LLM Settings ====================
BASE_URL=http://127.0.0.1:8004/v1
AGENT_MODEL=gpt-5.2
OPENAI_USE_RESPONSES_API=false
OPENAI_AGENTS_DISABLE_TRACING=1
# OPENAI_API_KEY=sk-...  # Optional if gateway requires auth

==================== MinerU PDF Parser ====================
MINERU_BASE_URL=https://mineru.net/api/v4
MINERU_API_TOKEN=your_mineru_token
MINERU_MODEL_VERSION=vlm
MINERU_POLL_TIMEOUT_SECONDS=900

==================== Paper Search (PASA) ====================
PAPER_SEARCH_ENABLED=true
PAPER_SEARCH_BASE_URL=http://127.0.0.1:8001
PAPER_SEARCH_ENDPOINT=/pasa/search
PAPER_SEARCH_HEALTH_ENDPOINT=/health
PAPER_SEARCH_API_KEY=

```

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

### Migration Step 2: Start PASA Server

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Commands to start the PASA server in the background and verify its health. Essential for the new decoupled architecture.

```bash
# 后台启动
cd <repo_root>/pasa
bash start_pasa_server.sh --background

# 验证启动成功
curl http://localhost:8001/health
```

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

### Install DeepReviewer 2.0

Source: https://github.com/researai/deepreviewer-v2/blob/main/README.md

Steps to install DeepReviewer 2.0 locally. Ensure you are in the repository root and have a Python virtual environment activated.

```bash
cd <repo_root>
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
```

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

### PASA Server Welcome Page Response

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example JSON response from the root GET endpoint, providing service information and available endpoints.

```json
{
  "service": "PASA Server",
  "version": "1.0.0",
  "status": "running",
  "description": "Independent Flask service for PASA paper search",
  "endpoints": {...}
}
```

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

### Start PASA Server in Foreground

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.md

Starts the PASA server in the foreground, which is recommended for debugging purposes. Ensure you are in the correct directory.

```bash
cd <repo_root>/pasa
bash start_pasa_server.sh
```

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

### Configure DeepReviewer 2.0 Environment

Source: https://github.com/researai/deepreviewer-v2/blob/main/README.md

Copy the example environment file and configure essential settings for LLM, MinerU, and optional paper search.

```bash
cp .env.example .env
```

```dotenv
# LLM (OpenAI-compatible)
BASE_URL=http://127.0.0.1:8004/v1
AGENT_MODEL=gpt-5.2
OPENAI_USE_RESPONSES_API=false
OPENAI_AGENTS_DISABLE_TRACING=1
# OPENAI_API_KEY=...  # optional if your gateway requires auth

# MinerU
MINERU_API_TOKEN=your_mineru_token

# Optional external paper search
PAPER_SEARCH_ENABLED=false

# Enable external search with PASA or a compatible service
# PAPER_SEARCH_ENABLED=true
PAPER_SEARCH_BASE_URL=http://127.0.0.1:8001
PAPER_SEARCH_API_KEY=
PAPER_SEARCH_ENDPOINT=/pasa/search
PAPER_SEARCH_HEALTH_ENDPOINT=/health
```

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

### Troubleshooting: Check Proxy Configuration

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example of proxy configuration in .pasa_env. Used when facing 'Connection error' when downloading arXiv papers.

```bash
http_proxy=http://127.0.0.1:58887
https_proxy=http://127.0.0.1:58887
```

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

### Configure PASA Environment Variables

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Copy the example environment file and edit it to set crucial configuration parameters for PASA, including GPU ID, server host/port, model paths, vLLM settings, Serper API key, and local paper database paths.

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

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

### Start PASA Server in Background

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.md

Starts the PASA server in the background, suitable for long-running use. Use this command when foreground debugging is not required.

```bash
cd <repo_root>/pasa
bash start_pasa_server.sh --background
```

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

### Example PASA Environment Configuration

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.md

Illustrates key environment variables for PASA configuration, including GPU settings, server host/port, model paths, vLLM service endpoints, Serper API key, and local paper database paths.

```bash
# GPU
PASA_GPU_ID=1

# Flask server
PASA_SERVER_HOST=0.0.0.0
PASA_SERVER_PORT=8001

# Model paths (must exist)
PASA_CRAWLER_PATH=/data/models/pasa-7b-crawler
PASA_SELECTOR_PATH=/data/models/pasa-7b-selector
PASA_PROMPTS_PATH=pasa/agent_prompt.json

# vLLM service endpoints
PASA_VLLM_HOST=127.0.0.1
PASA_VLLM_CRAWLER_PORT=8101
PASA_VLLM_SELECTOR_PORT=8102
PASA_VLLM_CRAWLER_URL=http://127.0.0.1:8101/v1
PASA_VLLM_SELECTOR_URL=http://127.0.0.1:8102/v1
PASA_VLLM_CRAWLER_MODEL_NAME=pasa-crawler
PASA_VLLM_SELECTOR_MODEL_NAME=pasa-selector

# Serper key (now read from env var; no longer hardcoded)
PASA_SERPER_API_KEY=your_serper_api_key
PASA_SERPER_SEARCH_URL=https://google.serper.dev/search

# Local paper DB (set real paths)
PASA_PAPER_DB=/data/pasa/cs_paper_2nd.zip
PASA_PAPER_ID=/data/pasa/id2paper.json
```

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

### Migration Guide

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Step-by-step instructions for migrating from the old `pasa_tool_heavy.py` to the new decoupled architecture, covering environment configuration, server startup, and code updates.

```APIDOC
## Migration Guide

### Migrating from `pasa_tool_heavy.py` to the New Architecture

**Step 1: Configure Environment**
```bash
# 1. Edit .pasa_env to configure GPU and model paths
vim pasa/.pasa_env

# 2. Verify PASA_SERVICE_URL in the main .env file
grep PASA_SERVICE_URL <project_root>/.env
```

**Step 2: Start PASA Server**
```bash
# Start in background
cd <repo_root>/pasa
bash start_pasa_server.sh --background

# Verify successful startup
curl http://localhost:8001/health
```

**Step 3: Update MCP Tool Configuration**

If using a custom MCP tool manager, replace `pasa_tool_heavy.py` with `pasa_tool.py`:

```python
# Old version
from backend.tools.pasa_tool_heavy import mcp as pasa_mcp

# New version
from backend.tools.pasa_tool import mcp as pasa_mcp
```

**Step 4: Test and Verify**
```bash
# Test the server API
curl -X POST http://localhost:8001/pasa/search \
  -H "Content-Type: application/json" \
  -d '{"query": "test query"}'

# Test MCP tool call in DirectorAgent
# (No code changes needed, transparent switching)
```
```

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

### Install PASA Dependencies

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Install necessary Python packages for PASA, including PyTorch, transformers, vLLM, Flask, and others. Ensure your Python environment meets the version requirements.

```bash
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
```

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

### Troubleshooting: Disable Proxy

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example of commenting out proxy settings in .pasa_env to disable proxy usage. Use this if the proxy is causing connection issues.

```bash
# http_proxy=
# https_proxy=
```

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

### Example PASA Environment Configuration

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

This is a minimal set of environment variables required for PASA to function, covering GPU, Flask server, model paths, vLLM, Serper API, and local paper DB.

```dotenv
# GPU
PASA_GPU_ID=1

# Flask
PASA_SERVER_HOST=0.0.0.0
PASA_SERVER_PORT=8001

# 模型路径（必须存在）
PASA_CRAWLER_PATH=/data/models/pasa-7b-crawler
PASA_SELECTOR_PATH=/data/models/pasa-7b-selector
PASA_PROMPTS_PATH=pasa/agent_prompt.json

# vLLM
PASA_VLLM_HOST=127.0.0.1
PASA_VLLM_CRAWLER_PORT=8101
PASA_VLLM_SELECTOR_PORT=8102
PASA_VLLM_CRAWLER_URL=http://127.0.0.1:8101/v1
PASA_VLLM_SELECTOR_URL=http://127.0.0.1:8102/v1
PASA_VLLM_CRAWLER_MODEL_NAME=pasa-crawler
PASA_VLLM_SELECTOR_MODEL_NAME=pasa-selector

# Serper（已改为环境变量配置，不再硬编码在代码中）
PASA_SERPER_API_KEY=your_serper_api_key
PASA_SERPER_SEARCH_URL=https://google.serper.dev/search

# 本地 paper DB（必须指向真实文件）
PASA_PAPER_DB=/data/pasa/cs_paper_2nd.zip
PASA_PAPER_ID=/data/pasa/id2paper.json
```

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

### Troubleshooting: Update PASA Service URL

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example of updating the PASA_SERVICE_URL in the main .env file. This should match the configured PASA_SERVER_PORT.

```bash
PASA_SERVICE_URL=http://localhost:8002
```

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

### Test PASA Search API

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example using curl to send a POST request to the PASA search API with specified parameters.

```bash
# 使用curl测试搜索API
curl -X POST http://localhost:8001/pasa/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Papers about contrastive learning for representation learning",
    "expand_layers": 2,
    "search_queries": 5,
    "search_papers": 10,
    "expand_papers": 20,
    "threads_num": 0
  }'
```

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

### Troubleshooting: Configure GPU ID

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example of setting the PASA_GPU_ID environment variable to specify which GPU to use. Apply this when encountering CUDA out of memory errors.

```bash
PASA_GPU_ID=1
```

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

### Troubleshooting: Configure PASA Server Port

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example of setting the PASA_SERVER_PORT environment variable to change the default server port. Use this if the default port is already in use.

```bash
PASA_SERVER_PORT=8002
```

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

### PASA Search API Response

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example JSON output from the PASA search API, containing a list of relevant papers with titles, links, and snippets.

```json
[
  {
    "title": "SimCLR: A Simple Framework for Contrastive Learning",
    "link": "2002.05709",
    "snippet": "This paper presents SimCLR: a simple framework for contrastive learning..."
  },
  ...
]
```

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

### Configuration - Environment Variables

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Configure the system through a .env file with LLM, MinerU, and paper search settings.

```APIDOC
## Configuration - Environment Variables

### Description
Configure the system through a `.env` file with LLM, MinerU, and paper search settings.

### Setup
Copy the example configuration file and modify it according to your needs.

```bash
cp .env.example .env
```

### Environment Variables

#### LLM Settings
- **BASE_URL** (string) - The base URL for the OpenAI-compatible LLM provider.
- **AGENT_MODEL** (string) - The model to be used by the agent.
- **OPENAI_USE_RESPONSES_API** (boolean) - Whether to use the responses API.
- **OPENAI_AGENTS_DISABLE_TRACING** (integer) - Disable tracing for agents.
- **OPENAI_API_KEY** (string) - Optional API key if the gateway requires authentication.

#### MinerU PDF Parser
- **MINERU_BASE_URL** (string) - The base URL for the MinerU PDF parsing service.
- **MINERU_API_TOKEN** (string) - API token for accessing MinerU.
- **MINERU_MODEL_VERSION** (string) - The model version to use with MinerU.
- **MINERU_POLL_TIMEOUT_SECONDS** (integer) - Timeout in seconds for MinerU polling.

#### Paper Search (PASA)
- **PAPER_SEARCH_ENABLED** (boolean) - Whether to enable the paper search functionality.
- **PAPER_SEARCH_BASE_URL** (string) - The base URL for the paper search service.
- **PAPER_SEARCH_ENDPOINT** (string) - The endpoint for performing paper searches.
- **PAPER_SEARCH_HEALTH_ENDPOINT** (string) - The endpoint for checking the health of the paper search service.
- **PAPER_SEARCH_API_KEY** (string) - API key for the paper search service.

### Example `.env` File Contents:
```dotenv
==================== LLM Settings ====================
BASE_URL=http://127.0.0.1:8004/v1
AGENT_MODEL=gpt-5.2
OPENAI_USE_RESPONSES_API=false
OPENAI_AGENTS_DISABLE_TRACING=1
# OPENAI_API_KEY=sk-...

==================== MinerU PDF Parser ====================
MINERU_BASE_URL=https://mineru.net/api/v4
MINERU_API_TOKEN=your_mineru_token
MINERU_MODEL_VERSION=vlm
MINERU_POLL_TIMEOUT_SECONDS=900

==================== Paper Search (PASA) ====================
PAPER_SEARCH_ENABLED=true
PAPER_SEARCH_BASE_URL=http://127.0.0.1:8001
PAPER_SEARCH_ENDPOINT=/pasa/search
PAPER_SEARCH_HEALTH_ENDPOINT=/health
PAPER_SEARCH_API_KEY=
```
```

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

### Main Configuration (.env)

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Primary configuration file for backend tools to connect to the PASA server URL.

```bash
# PASA服务配置 (后端工具使用)
PASA_SERVICE_URL=http://localhost:8001
```

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

### Get Job Status Snapshot

Source: https://github.com/researai/deepreviewer-v2/blob/main/README.md

Retrieve a one-shot status update for a specific job using its ID.

```bash
python main.py status --job-id <job_id>
```

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

### Check Job Status

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Get a one-shot status snapshot of a review job including progress, annotations, and usage statistics.

```APIDOC
## Check Job Status

### Description
Get a one-shot status snapshot of a review job including progress, annotations, and usage statistics.

### Method
`GET` (conceptual, as it's a CLI command)

### Endpoint
`python main.py status`

### Parameters
#### Command Line Arguments
- **--job-id** (string) - Required - The unique identifier of the review job.

### Request Example
```bash
python main.py status --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the review job.
- **status** (string) - The current status of the job (e.g., "agent_running", "completed").
- **message** (string) - A message describing the current state.
- **error** (string or null) - Any error message if the job failed.
- **annotation_count** (integer) - The number of annotations generated.
- **final_report_ready** (boolean) - Indicates if the final report is ready.
- **pdf_ready** (boolean) - Indicates if the final PDF report is ready.
- **usage** (object) - Detailed usage statistics (token, tool, paper_search).
- **artifacts** (object) - Paths to generated artifacts like source PDF and markdown.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "agent_running",
  "message": "Running review agent with tool loop...",
  "error": null,
  "annotation_count": 8,
  "final_report_ready": false,
  "pdf_ready": false,
  "usage": {
    "token": {"requests": 12, "input_tokens": 45000, "output_tokens": 8000, "total_tokens": 53000},
    "tool": {"total_calls": 25, "distinct_tools": 5, "per_tool": {"pdf_search": 8, "pdf_annotate": 8}},
    "paper_search": {"total_calls": 3, "successful_calls": 3, "distinct_queries": 3}
  },
  "artifacts": {
    "source_pdf_path": "data/jobs/<job_id>/source.pdf",
    "mineru_markdown_path": "data/jobs/<job_id>/mineru.md"
  }
}
```
```

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

### Check PASA Server Health

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Send a GET request to the /health endpoint to verify the status of the PASA server and its components (crawler, selector).

```bash
curl http://127.0.0.1:8001/health
```

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

### Developer Notes: Modify MCP Tool Timeout

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example of changing the HTTP request timeout for the MCP tool by modifying `PASA_REQUEST_TIMEOUT` in `pasa_tool.py`.

```python
PASA_REQUEST_TIMEOUT = 300.0  # 修改为更长或更短的超时时间(秒)
```

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

### Migration Step 1: Configure Environment

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Steps to configure the environment for migrating to the new PASA architecture. Involves editing .pasa_env and verifying .env.

```bash
# 1. 编辑.pasa_env配置GPU和模型路径
vim pasa/.pasa_env

# 2. 验证主.env中的PASA_SERVICE_URL
grep PASA_SERVICE_URL <project_root>/.env
```

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

### Download PASA Models using huggingface-cli

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Download the PASA crawler and selector models from Hugging Face to specified local directories. Ensure these paths exist and are accessible.

```bash
# 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
```

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

### Troubleshooting: Check Model Paths

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Command to verify the existence of PASA model files. Use this when encountering 'Failed to load PASA models: FileNotFoundError'.

```bash
ls /path/to/pasa-7b-crawler
ls /path/to/pasa-7b-selector
ls <repo_root>/pasa/pasa/agent_prompt.json
```

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

### PASA vLLM Configuration (.pasa_env)

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Configuration file for vLLM and PASA, specifying GPU, model paths, server ports, and proxy settings.

```bash
# GPU设备（按要求使用 1 号卡）
PASA_GPU_ID=1

# 模型路径 (必须存在)
PASA_CRAWLER_PATH=/path/to/pasa-7b-crawler
PASA_SELECTOR_PATH=/path/to/pasa-7b-selector
PASA_PROMPTS_PATH=pasa/agent_prompt.json

# 服务器网络配置
PASA_SERVER_HOST=0.0.0.0
PASA_SERVER_PORT=8001

# vLLM OpenAI server
PASA_VLLM_CRAWLER_URL=http://127.0.0.1:8101/v1
PASA_VLLM_SELECTOR_URL=http://127.0.0.1:8102/v1
PASA_VLLM_CRAWLER_MODEL_NAME=pasa-crawler
PASA_VLLM_SELECTOR_MODEL_NAME=pasa-selector

# arXiv访问代理
http_proxy=http://127.0.0.1:58887
https_proxy=http://127.0.0.1:58887
```

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

### POST /pasa/search API Response Body

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Example structure for the response from the PASA search API, containing a list of papers with their titles, links, and snippets.

```json
[
  {
    "title": "Paper Title",
    "link": "arxiv_id",
    "snippet": "Abstract text"
  }
]
```

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

### Fetch Review Results

Source: https://github.com/researai/deepreviewer-v2/blob/main/README.md

Commands to retrieve the review results in various formats. Specify the desired format using the `--format` flag.

```bash
python main.py result --job-id <job_id> --format all
```

```bash
python main.py result --job-id <job_id> --format md
```

```bash
python main.py result --job-id <job_id> --format pdf
```

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

### PASA Project File Structure

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Overview of the directory structure for the PASA tool, including server, configuration, and pipeline code.

```text
pasa/
├── pasa_server.py              # Flask服务 (流程编排,通过HTTP调用vLLM)
├── .pasa_env                   # vLLM+PASA配置 (GPU、模型路径、端口、代理)
├── start_pasa_server.sh        # 启动脚本 (启动2个vLLM + 1个Flask)
├── test_pasa_decoupling.py     # 测试脚本
└── pasa/                       # PASA pipeline代码 (含 vllm_agent)

<project_root>/
└── .env                        # 主配置 (PASA服务URL)
```

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

### PASA Architecture Diagram (Before)

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Illustrates the previous monolithic architecture where the model was loaded on each call.

```text
DirectorAgent (MCP) → pasa_tool_heavy.py → 加载模型 → GPU推理 → 返回结果
                       ↑ 每次调用都加载模型(慢)
```

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

### PASA Architecture Diagram (After)

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Shows the current decoupled architecture with a Flask service calling a vLLM server for model inference.

```text
DirectorAgent (MCP) → pasa_tool.py (轻量级HTTP客户端)
                           ↓ HTTP请求
                     pasa_server.py (独立Flask编排服务)
                           ↓ HTTP请求
               vLLM(OpenAI Server) crawler + selector (模型常驻GPU)
                      GPU推理 → 返回结果
```

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

### Migration Step 3: Update MCP Tool Configuration

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Illustrates how to switch from the old `pasa_tool_heavy.py` to the new `pasa_tool.py` in Python imports for MCP tools.

```python
# 旧版本
from backend.tools.pasa_tool_heavy import mcp as pasa_mcp

# 新版本
from backend.tools.pasa_tool import mcp as pasa_mcp
```

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

### Performance Comparison

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Compares the performance metrics of the old architecture (pasa_tool_heavy.py) with the new decoupled architecture, highlighting improvements in latency, resource utilization, and concurrency.

```APIDOC
## Performance Comparison

### Old Architecture (pasa_tool_heavy.py)

| Metric | Value |
|---|---|
| Initial Call Latency | 60-180 seconds (includes model loading) |
| Subsequent Call Latency | 30-120 seconds (search time) |
| GPU Utilization Duration | During call |
| Concurrency | Low (limited by MCP process) |

### New Architecture (Decoupled)

| Metric | Value |
|---|---|
| Server Startup Time | 60-180 seconds (one-time) |
| Per-Call Latency | 30-120 seconds (search time only) |
| GPU Utilization Duration | During server runtime (persistent) |
| Concurrency | High (Flask multithreading) |

### Summary of Advantages

✅ **Startup Time:** Models loaded once, no waiting for subsequent calls.
✅ **Response Speed:** 2-6x faster initial call.
✅ **Resource Isolation:** Independent GPU management, no impact on main process.
✅ **Scalability:** Can be deployed on dedicated GPU servers.
✅ **Maintainability:** Independent server restarts, no impact on main system.
```

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

### Configure DeepReviewer to Use PASA

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Set environment variables in the DeepReviewer's .env file to point to the PASA service's base URL and search endpoint.

```bash
PAPER_SEARCH_BASE_URL=http://127.0.0.1:8001
PAPER_SEARCH_ENDPOINT=/pasa/search
PAPER_SEARCH_API_KEY=
```

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

### Fetch Review Results

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Retrieve the final review outputs. Specify the desired format: 'all' for markdown content and file paths, 'md' for markdown content only, or 'pdf' for the report PDF file path.

```bash
python main.py result --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format all
```

```bash
python main.py result --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format md
```

```bash
python main.py result --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format pdf
```

```json
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "final_markdown_path": "data/jobs/<job_id>/final_report.md",
  "report_pdf_path": "data/jobs/<job_id>/final_report.pdf",
  "final_markdown": "## Summary\n\nThis paper presents..."
}
```

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

### Developer Notes: PASA Tool Logging

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Information on how to enable DEBUG level logging for `pasa_tool.py` by setting the LOG_LEVEL environment variable.

```bash
# MCP工具日志通过FastMCP框架管理
# 查看日志需在运行时设置环境变量
export LOG_LEVEL=DEBUG
```

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

### Developer Notes

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Provides guidance for developers on modifying server configurations, adjusting tool timeouts, and enabling debug logging for the PASA server and tools.

```APIDOC
## Developer Notes

### Code Modification Suggestions

#### Modifying PASA Server Configuration
To change default parameters, edit the `run_pasa_search` function in `pasa_server.py`:

```python
def run_pasa_search(
    query: str,
    expand_layers: int = 2,        # Modify here
    search_queries: int = 5,       # Modify here
    search_papers: int = 10,       # Modify here
    expand_papers: int = 20,       # Modify here
    threads_num: int = 0,          # Modify here
) -> List[Dict[str, str]]:
    ...
```

#### Modifying MCP Tool Timeout
To adjust the HTTP request timeout, edit `pasa_tool.py`:

```python
PASA_REQUEST_TIMEOUT = 300.0  # Adjust to a longer or shorter timeout (seconds)
```

### Log Debugging

**PASA Server Log Level:**
```python
# Modify in pasa_server.py
logging.basicConfig(
    level=logging.DEBUG,  # Change to DEBUG for verbose logs
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```

**pasa_tool.py Logs:**
```python
# MCP tool logs are managed by the FastMCP framework.
# Set the environment variable to view logs during runtime:
export LOG_LEVEL=DEBUG
```
```

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

### Submit a New Review Job

Source: https://github.com/researai/deepreviewer-v2/blob/main/README.md

Use this command to submit a PDF file for a new review job.

```bash
python main.py submit --pdf /path/to/paper.pdf
```

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

### PASA Tool Usage in MCP

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Illustrates how the `pasa_tool.py` is automatically called by DirectorAgent, abstracting the underlying HTTP requests to the PASA server.

```python
# DirectorAgent内部调用示例
results = await pasa_search(
    query="Papers on efficient transformers"
)
# pasa_tool.py透明地转发请求到pasa_server.py
```

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

### View PASA Server Logs

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Command to view the real-time logs of the PASA server running in the background.

```bash
tail -f /tmp/pasa_server.log
```

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

### Edit .pasa_env Configuration

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Commands to edit the PASA vLLM configuration file using vim or nano.

```bash
vim pasa/.pasa_env
# 或
nano pasa/.pasa_env
```

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

### Troubleshooting: Check GPU Usage

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Command to check current GPU utilization. Useful for diagnosing 'RuntimeError: CUDA out of memory' issues.

```bash
nvidia-smi
```

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

### Migration Step 4: Test Verification

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Commands to test the PASA server API directly and to confirm that MCP tool calls are transparently switched to the new architecture.

```bash
# 测试服务器API
curl -X POST http://localhost:8001/pasa/search \
  -H "Content-Type: application/json" \
  -d '{"query": "test query"}'

# 在DirectorAgent中测试MCP工具调用
# (无需修改调用代码,透明切换)
```

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

### Run PASA Test Script

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/README.zh-CN.md

Execute the provided Python script to test the decoupling functionality of the PASA service.

```bash
cd <repo_root>/pasa
python test_pasa_decoupling.py
```

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

### Developer Notes: Modify PASA Server Configuration

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Shows how to modify default parameters for the PASA server by editing the `run_pasa_search` function in `pasa_server.py`.

```python
def run_pasa_search(
    query: str,
    expand_layers: int = 2,        # 修改此处
    search_queries: int = 5,       # 修改此处
    search_papers: int = 10,       # 修改此处
    expand_papers: int = 20,       # 修改此处
    threads_num: int = 0,          # 修改此处
) -> List[Dict[str, str]]:
    ...
```

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

### Submit a PDF Review Job

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Submit a PDF file for review. Use `--wait-seconds 0` to return immediately with a job ID, or specify a duration to wait for completion. The output includes job status and initial usage statistics.

```bash
python main.py submit --pdf /path/to/paper.pdf --wait-seconds 0
```

```bash
python main.py submit --pdf /path/to/paper.pdf --title "My Paper Review" --wait-seconds 60
```

```json
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "message": "Job queued.",
  "completed": false,
  "usage": {
    "token": {"requests": 0, "input_tokens": 0, "output_tokens": 0, "total_tokens": 0},
    "tool": {"total_calls": 0, "distinct_tools": 0, "per_tool": {}},
    "paper_search": {"total_calls": 0, "successful_calls": 0, "effective_calls": 0}
  }
}
```

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

### Troubleshooting Common Issues

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Provides solutions for common problems encountered when running the DeepReviewer v2 system, including model loading failures, GPU issues, port conflicts, server connection problems, and proxy configurations.

```APIDOC
## Troubleshooting Common Issues

### Problem 1: Model Loading Failed

**Symptom:**
```
❌ Failed to load PASA models: FileNotFoundError
```

**Solution:**
1. Verify that the model paths in `.pasa_env` exist:
   ```bash
   ls /path/to/pasa-7b-crawler
   ls /path/to/pasa-7b-selector
   ls <repo_root>/pasa/pasa/agent_prompt.json
   ```
2. Correct the paths in `.pasa_env` and restart the server.

### Problem 2: GPU Unavailable

**Symptom:**
```
RuntimeError: CUDA out of memory
```

**Solution:**
1. Check GPU utilization:
   ```bash
   nvidia-smi
   ```
2. Update `PASA_GPU_ID` in `.pasa_env` to an available GPU ID:
   ```bash
   PASA_GPU_ID=1
   ```
3. Restart the PASA server.

### Problem 3: Port Already in Use

**Symptom:**
```
OSError: [Errno 98] Address already in use
```

**Solution:**
1. Find the process using the port:
   ```bash
   lsof -i :8001
   ```
2. Terminate the process or change the port in `.pasa_env`:
   ```bash
   PASA_SERVER_PORT=8002
   ```
3. Update `PASA_SERVICE_URL` in the main `.env` file accordingly:
   ```bash
   PASA_SERVICE_URL=http://localhost:8002
   ```

### Problem 4: `pasa_tool.py` Connection Failure

**Symptom:**
```
RuntimeError: PASA server at http://localhost:8001 is not healthy or not reachable
```

**Solution:**
1. Ensure the PASA server is running:
   ```bash
   curl http://localhost:8001/health
   ```
2. Verify the `PASA_SERVICE_URL` in `.env` is correct.
3. Check firewall and network connectivity.

### Problem 5: arXiv Access Issues due to Proxy

**Symptom:**
```
Failed to download arxiv paper: Connection error
```

**Solution:**
1. Review proxy settings in `.pasa_env`:
   ```bash
   http_proxy=http://127.0.0.1:58887
   https_proxy=http://127.0.0.1:58887
   ```
2. Confirm the proxy server is running.
3. If a proxy is not needed, comment out or remove these lines:
   ```bash
   # http_proxy=
   # https_proxy=
   ```
```

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

### Parse PDF Documents with MinerU Adapter

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Parse PDF documents into structured markdown using the MinerU adapter. This function configures the adapter with API details and processing options, then calls the PDF parsing method.

```python
import asyncio
from pathlib import Path
from deepreview.adapters.mineru import MineruAdapter, MineruConfig

async def parse_pdf(pdf_path: str) -> dict:
    config = MineruConfig(
        base_url="https://mineru.net/api/v4",
        api_token="your_mineru_token",
        model_version="vlm",
        upload_endpoint="/file-urls/batch",
        poll_endpoint_templates=[
            "/extract-results/batch/{batch_id}",
            "/extract-results/{batch_id}"
        ],
        poll_interval_seconds=3.0,
        poll_timeout_seconds=900,
        allow_local_fallback=True  # Use pypdf if MinerU fails
    )

    adapter = MineruAdapter(config)

    result = await adapter.parse_pdf(
        pdf_path=Path(pdf_path),
        data_id="my-document-001"
    )

    return {
        "markdown": result.markdown[:1000] + "...",  # Truncated for display
        "content_list_items": len(result.content_list or []),
        "provider": result.provider,
        "batch_id": result.batch_id,
        "warning": result.warning
    }

# Example usage
result = asyncio.run(parse_pdf("/path/to/paper.pdf"))
print(f"Parsed with {result['provider']}: {result['content_list_items']} content items")
if result['warning']:
    print(f"Warning: {result['warning']}")
```

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

### Search Academic Papers Programmatically

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Search for academic papers using the Paper Search Adapter. Configure search and read settings, check service availability, and execute searches with optional questions.

```python
import asyncio
from deepreview.adapters.paper_search import (
    PaperSearchAdapter,
    PaperSearchConfig,
    PaperReadConfig
)

async def search_papers(query: str, questions: list[str] = None):
    # Configure adapter
    search_cfg = PaperSearchConfig(
        enabled=True,
        base_url="http://127.0.0.1:8001",
        api_key=None,
        endpoint="/pasa/search",
        timeout_seconds=120,
        health_endpoint="/health",
        health_timeout_seconds=5
    )
    read_cfg = PaperReadConfig(
        base_url=None,
        api_key=None,
        endpoint="/read",
        timeout_seconds=180
    )

    adapter = PaperSearchAdapter(search_cfg, read_cfg)

    # Check service availability
    state = await adapter.get_search_runtime_state()
    if not state.started:
        print(f"Paper search not available: {state.availability}")
        # Falls back to arXiv search automatically

    # Execute search
    result = await adapter.search(
        query=query,
        question_list=questions or []
    )

    return result

# Example usage
result = asyncio.run(search_papers(
    query="attention mechanisms in transformers",
    questions=[
        "What are efficient attention variants?",
        "How does flash attention work?"
    ]
))

for paper in result.get("papers", [])[:5]:
    print(f"- {paper['title']}")
    print(f"  arXiv: {paper.get('arxiv_id', 'N/A')}")
    print(f"  URL: {paper.get('url', 'N/A')}")
```

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

### Perform Synchronous Paper Search

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Execute a paper search query synchronously. The request will block until the search results are compiled and returned. Configure search parameters like query depth and number of results.

```bash
curl -X POST http://127.0.0.1:8001/pasa/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Papers about vision transformers for medical imaging",
    "expand_layers": 2,
    "search_queries": 5,
    "search_papers": 10,
    "expand_papers": 20,
    "threads_num": 0
  }'
```

```json
[
  {
    "title": "Medical Image Analysis with Vision Transformers: A Survey",
    "link": "2312.12345",
    "snippet": "This survey comprehensively reviews the application of Vision Transformers..."
  },
  {
    "title": "ViT-Med: Adapting Vision Transformers for Medical Image Classification",
    "link": "2311.67890",
    "snippet": "We propose ViT-Med, a specialized architecture that adapts..."
  }
]
```

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

### Fetch Job Results

Source: https://github.com/researai/deepreviewer-v2/blob/main/README.md

Retrieve the final outputs for a completed job, including markdown and PDF formats.

```bash
python main.py result --job-id <job_id> --format all
```

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

### Developer Notes: PASA Server Log Level

Source: https://github.com/researai/deepreviewer-v2/blob/main/pasa/PASA_DECOUPLING_README.md

Instructions on how to change the logging level for the PASA server to DEBUG for more detailed logs, by modifying `logging.basicConfig` in `pasa_server.py`.

```python
# 在pasa_server.py中修改
logging.basicConfig(
    level=logging.DEBUG,  # 改为DEBUG获取详细日志
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```

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

### Submit Asynchronous Paper Search Job

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Initiate a paper search job that runs in the background. This endpoint returns a job ID and URLs to track the job's progress and retrieve results once completed.

```bash
# Submit async job
curl -X POST http://127.0.0.1:8001/pasa/search_async \
  -H "Content-Type: application/json" \
  -d '{"query": "Large language models for code generation"}'
```

```json
{
  "job_id": "abc123def456",
  "status": "queued",
  "status_url": "/pasa/jobs/abc123def456",
  "result_url": "/pasa/jobs/abc123def456/result"
}
```

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

### Run a Review Job Programmatically

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Execute a complete review job using the Python API. This function handles job state creation, artifact management, and pipeline execution.

```python
import asyncio
from pathlib import Path
from deepreview.runner import run_job_async
from deepreview.state import load_job_state, save_job_state
from deepreview.types import JobState, JobStatus

async def run_review(pdf_path: str, title: str = "My Paper") -> dict:
    # Create job state
    pdf = Path(pdf_path)
    job = JobState(
        title=title,
        source_pdf_name=pdf.name,
    )
    save_job_state(job)

    # Copy PDF to job directory
    from deepreview.state import ensure_artifact_paths
    import shutil
    artifacts = ensure_artifact_paths(job.id)
    shutil.copy2(pdf_path, artifacts['source_pdf'])

    # Update job with source path
    loaded = load_job_state(job.id)
    loaded.artifacts.source_pdf_path = str(artifacts['source_pdf'])
    save_job_state(loaded)

    # Run the review pipeline
    try:
        await run_job_async(str(job.id))
    except Exception as e:
        print(f"Review failed: {e}")
        return {"status": "failed", "error": str(e)}

    # Get final results
    final_job = load_job_state(job.id)
    return {
        "job_id": str(final_job.id),
        "status": final_job.status.value,
        "final_markdown_path": final_job.artifacts.final_markdown_path,
        "report_pdf_path": final_job.artifacts.report_pdf_path,
        "usage": final_job.usage.model_dump(),
        "annotation_count": final_job.annotation_count
    }

# Execute
result = asyncio.run(run_review("/path/to/paper.pdf", "Vision Transformer Analysis"))
print(f"Review completed: {result['report_pdf_path']}")
```

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

### Call review_final_markdown_write Tool

Source: https://context7.com/researai/deepreviewer-v2/llms.txt

Use the review_final_markdown_write tool to submit the final review report. This tool supports section-by-section submission, which is the recommended mode.

```python
# Tool call by agent - section mode (recommended)
result = await review_final_markdown_write(
    ctx,
    section_id="summary",
    section_content="""
This paper introduces a novel approach to vision-language pretraining using
contrastive learning with hard negative mining. The core contribution is a
dynamic negative sampling strategy that improves representation quality.
"""
)
```