# tiger-ai-lab/openresearcher architecture

> Architecture diagram of the GitHub repository tiger-ai-lab/openresearcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiger-ai-lab/openresearcher
- Repository: https://github.com/tiger-ai-lab/openresearcher

## Overview

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

Main entry points: [`deploy_agent.py`](https://github.com/tiger-ai-lab/openresearcher/blob/main/deploy_agent.py) (Agent orchestration), [`backend.py`](https://github.com/tiger-ai-lab/openresearcher/blob/main/backend.py) (Local search service), [`browser.py`](https://github.com/tiger-ai-lab/openresearcher/blob/main/browser.py) (Browser environment), [`utils/openai_generator.py`](https://github.com/tiger-ai-lab/openresearcher/blob/main/utils/openai_generator.py) (OpenAI generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runner"]
  node_batch_launcher["Batch launcher<br/>shell entry point<br/>[run_agent.sh]"]
  node_agent_runner["Agent orchestration<br/>Python control plane<br/>[deploy_agent.py]"]
  node_browser["Browser environment<br/>agent tool layer<br/>[browser.py]"]
end

subgraph group_retrieval["Retrieval boundary"]
  node_serper(("Serper Search API<br/>external web search"))
  node_local_search["Local search service<br/>HTTP retrieval service<br/>[backend.py]"]
  node_search_deploy["Search deployment<br/>service launcher"]
  node_search_start["Search start script<br/>service launcher"]
  node_retrieval_assets[("Corpus &amp; retrieval index<br/>BM25/dense assets")]
end

subgraph group_model["Model serving"]
  node_generator["OpenAI generator<br/>model adapter"]
  node_vllm_adapter["vLLM adapter<br/>model adapter<br/>[vllm_generator.py]"]
  node_vllm_service["vLLM model servers<br/>GPU inference service"]
end

subgraph group_benchmark["Benchmarks &amp; evaluation"]
  node_datasets["Dataset preparation<br/>benchmark data loader<br/>[data_utils.py]"]
  node_setup["Environment setup<br/>bootstrap script<br/>[setup.sh]"]
  node_run_outputs[("Run artifacts<br/>saved trajectories")]
  node_evaluator["Result evaluation<br/>benchmark scorer<br/>[eval.py]"]
  node_openai_eval(("OpenAI evaluation API<br/>external evaluation service"))
end

node_batch_launcher -->|"launches"| node_agent_runner
node_datasets -->|"task records"| node_agent_runner
node_setup -->|"preloads"| node_datasets
node_agent_runner -->|"generation requests"| node_generator
node_agent_runner -->|"per-task tools"| node_browser
node_generator -->|"OpenAI-compatible calls"| node_vllm_service
node_vllm_adapter -.->|"alternate calls"| node_vllm_service
node_browser -->|"external search mode"| node_serper
node_browser -->|"local search mode"| node_local_search
node_search_deploy -->|"deploys"| node_local_search
node_search_start -->|"starts"| node_local_search
node_local_search -->|"queries"| node_retrieval_assets
node_agent_runner -->|"writes trajectories"| node_run_outputs
node_run_outputs -->|"saved runs"| node_evaluator
node_evaluator -.->|"configured scoring"| node_openai_eval

click node_batch_launcher "https://github.com/tiger-ai-lab/openresearcher/blob/main/run_agent.sh"
click node_agent_runner "https://github.com/tiger-ai-lab/openresearcher/blob/main/deploy_agent.py"
click node_browser "https://github.com/tiger-ai-lab/openresearcher/blob/main/browser.py"
click node_local_search "https://github.com/tiger-ai-lab/openresearcher/blob/main/backend.py"
click node_search_deploy "https://github.com/tiger-ai-lab/openresearcher/blob/main/scripts/deploy_search_service.py"
click node_search_start "https://github.com/tiger-ai-lab/openresearcher/blob/main/scripts/start_search_service.sh"
click node_generator "https://github.com/tiger-ai-lab/openresearcher/blob/main/utils/openai_generator.py"
click node_vllm_adapter "https://github.com/tiger-ai-lab/openresearcher/blob/main/utils/vllm_generator.py"
click node_vllm_service "https://github.com/tiger-ai-lab/openresearcher/blob/main/scripts/deploy_vllm_service.py"
click node_datasets "https://github.com/tiger-ai-lab/openresearcher/blob/main/data_utils.py"
click node_setup "https://github.com/tiger-ai-lab/openresearcher/blob/main/setup.sh"
click node_evaluator "https://github.com/tiger-ai-lab/openresearcher/blob/main/eval.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_batch_launcher,node_agent_runner,node_browser toneBlue
class node_serper,node_local_search,node_search_deploy,node_search_start,node_retrieval_assets toneAmber
class node_generator,node_vllm_adapter,node_vllm_service toneMint
class node_datasets,node_setup,node_run_outputs,node_evaluator,node_openai_eval toneRose
```

## Components

### Agent runner

- [Batch launcher](https://github.com/tiger-ai-lab/openresearcher/blob/main/run_agent.sh): shell entry point · `run_agent.sh`
- [Agent orchestration](https://github.com/tiger-ai-lab/openresearcher/blob/main/deploy_agent.py): Python control plane · Runs tasks concurrently and manages browser and model resources. · `deploy_agent.py`
- [Browser environment](https://github.com/tiger-ai-lab/openresearcher/blob/main/browser.py): agent tool layer · Exposes iterative search and browsing tools to the model. · `browser.py`

### Retrieval boundary

- **Serper Search API**: external web search
- [Local search service](https://github.com/tiger-ai-lab/openresearcher/blob/main/backend.py): HTTP retrieval service · Serves BrowseComp-Plus retrieval independently of agent workers. · `backend.py`
- [Search deployment](https://github.com/tiger-ai-lab/openresearcher/blob/main/scripts/deploy_search_service.py): service launcher · Selects retrieval mode and service port. · `scripts/deploy_search_service.py`
- [Search start script](https://github.com/tiger-ai-lab/openresearcher/blob/main/scripts/start_search_service.sh): service launcher · `scripts/start_search_service.sh`
- **Corpus & retrieval index**: BM25/dense assets · BrowseComp-Plus corpus and dense retrieval assets.

### Model serving

- [OpenAI generator](https://github.com/tiger-ai-lab/openresearcher/blob/main/utils/openai_generator.py): model adapter · Normalizes OpenAI-compatible generation and native tool calls. · `utils/openai_generator.py`
- [vLLM adapter](https://github.com/tiger-ai-lab/openresearcher/blob/main/utils/vllm_generator.py): model adapter · `utils/vllm_generator.py`
- [vLLM model servers](https://github.com/tiger-ai-lab/openresearcher/blob/main/scripts/deploy_vllm_service.py): GPU inference service · Hosts OpenResearcher-30B-A3B across one or more server ports. · `scripts/deploy_vllm_service.py`

### Benchmarks & evaluation

- [Dataset preparation](https://github.com/tiger-ai-lab/openresearcher/blob/main/data_utils.py): benchmark data loader · Produces task records for BrowseComp, BrowseComp-Plus, GAIA, and xbench. · `data_utils.py`
- [Environment setup](https://github.com/tiger-ai-lab/openresearcher/blob/main/setup.sh): bootstrap script · Creates the environment and preloads BrowseComp-Plus. · `setup.sh`
- **Run artifacts**: saved trajectories · Per-task research outputs persisted by the runner.
- [Result evaluation](https://github.com/tiger-ai-lab/openresearcher/blob/main/eval.py): benchmark scorer · Rescores saved run directories with benchmark-specific scoring. · `eval.py`
- **OpenAI evaluation API**: external evaluation service

## Connections

- Batch launcher → Agent orchestration: launches
- Dataset preparation → Agent orchestration: task records
- Environment setup → Dataset preparation: preloads
- Agent orchestration → OpenAI generator: generation requests
- Agent orchestration → Browser environment: per-task tools
- OpenAI generator → vLLM model servers: OpenAI-compatible calls
- vLLM adapter → vLLM model servers: alternate calls
- Browser environment → Serper Search API: external search mode
- Browser environment → Local search service: local search mode
- Search deployment → Local search service: deploys
- Search start script → Local search service: starts
- Local search service → Corpus & retrieval index: queries
- Agent orchestration → Run artifacts: writes trajectories
- Run artifacts → Result evaluation: saved runs
- Result evaluation → OpenAI evaluation API: configured scoring