tiger-ai-lab/openresearcher

Purpose and Entry Points

OpenResearcher is a Python deep-research agent runner and benchmark harness for the OpenResearcher-30B-A3B model. It executes long-horizon research tasks by coupling an OpenAI-compatible LLM service with browser/search tools, persists run outputs, and scores benchmark results.

Primary entry points:

• Batch benchmark execution: run_agent.sh, deploy_agent.py

• Single-task programmatic execution: deploy_agent.py

• Result evaluation: eval.py

• Local search service: backend.py, scripts/start_search_service.sh

Agent Orchestration

deploy_agent.py is the core control plane. It exposes run_one for an individual question and manages concurrent benchmark task execution, model-server routing, per-task browser instances, and cleanup. It connects a generator abstraction to browser tools so the model can iteratively issue native tool calls and produce a final research answer.

Grounding: deploy_agent.py, run_agent.sh, browser.py

Browser and Search Boundary

browser.py provides the agent-facing browsing/search environment, while search is deliberately swappable:

• serper sends queries to Serper’s Google Search API.

• local targets the repository’s separately deployed retrieval service.

This separates agent behavior from retrieval implementation and makes BrowseComp-Plus runnable against its local corpus/index while other benchmarks use external web search.

Grounding: browser.py, backend.py, .env.template

Local Retrieval Service

backend.py serves local BM25 or dense retrieval over the BrowseComp-Plus corpus. Search deployment is operationally independent from agent execution, allowing the agent to consume it over HTTP rather than load corpus/index state itself. Deployment scripts select retrieval mode and service port.

Grounding: backend.py, scripts/deploy_search_service.py, scripts/start_search_service.sh

Model Generation Layer

Generator adapters normalize calls to OpenAI-compatible inference servers. The primary intended runtime is vLLM hosting OpenResearcher-30B-A3B, with native tool use enabled; an alternate vLLM-specific adapter is also present. Agent workers can distribute requests across multiple model-server ports.

Grounding: utils/openai_generator.py, utils/vllm_generator.py, scripts/deploy_vllm_service.py

Benchmark Data and Execution Flow

data_utils.py loads or prepares supported datasets—BrowseComp-Plus, BrowseComp, GAIA text, and xbench-DeepResearch—into task records consumed by the deployment runner. setup.sh establishes the Python environment and preloads BrowseComp-Plus; other benchmark datasets are obtained on first use. The flow is: dataset task → agent/model/browser loop → output directory artifacts → evaluator.

Grounding: data_utils.py, setup.sh, run_agent.sh

Evaluation

eval.py consumes saved run directories and applies benchmark-appropriate scoring, including OpenAI API-backed evaluation where configured. Evaluation is decoupled from inference so existing trajectories can be rescored without rerunning research.

Grounding: eval.py, .env.template

Runtime and Infrastructure

The project targets Linux, Python 3.12, CUDA-capable multi-GPU machines (documented around 8×A100 80GB), and Java 21. vLLM serves model replicas/tensor-parallel workers; local dense search deploys Qwen3-Embedding-8B. External dependencies include Hugging Face-hosted models/datasets, Serper, OpenAI evaluation APIs, and Tevatron for BrowseComp-Plus retrieval assets.

Grounding: pyproject.toml, scripts/start_nemotron_servers.sh, scripts/stop_servers.sh