# ruc-nlpir/webthinker architecture

> Architecture diagram of the GitHub repository ruc-nlpir/webthinker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruc-nlpir/webthinker
- Repository: https://github.com/ruc-nlpir/webthinker

## Overview

##### Project Type and Purpose
- WebThinker is a Python‐based research framework (a full‐stack CLI + demo application without a traditional frontend) that empowers large reasoning models (LRMs) to autonomously search the web, extract information, and generate research reports end to end.

##### High-Level Architecture Components
A. User Interfaces
- CLI Scripts (“scripts/run_web_thinker.py”, “scripts/run_web_thinker_report.py”, etc.)
- Demo UI (Streamlit app in demo/run_demo.py)
B. Orchestration Layer
- Main Orchestrator modules in “scripts/run_*.py”
- Demo controller in “demo/run_demo.py”
C. Tooling & Connectors
- Deep Web Explorer: scripts/search/bing_search.py + optional Crawl4AI client
- Prompt modules: “demo/prompts.py”, “scripts/prompts/prompts.py”, lcb_runner/prompts
D. LLM Invocation Layer
- lcb_runner framework (“scripts/lcb_runner/runner/…”) abstracts calls to vLLM‐served models (main reasoning and auxiliary)
- Pluggable runners for OpenAI, Gemini, Qwen, Claude, etc.
E. Data Layer
- Local benchmarks and question sets (“data/GAIA”, “data/GPQA”, etc.)
- Outputs folder storing generated markdown reports (“outputs/…”)
F. Evaluation Layer
- scripts/evaluate/evaluate.py (QA evaluation)
- scripts/evaluate/evaluate_report.py (report quality evaluation)

##### Relationships and Data Flows
- User (CLI or Demo UI) → invokes Orchestrator
- Orchestrator → calls Deep Web Explorer to issue Bing Search API requests and parse results
- Retrieved web content → fed into LLM Invocation Layer (via lcb_runner)
- LLMs (main reasoning model & auxiliary model) ↔ Orchestrator: multi-step think→search→draft cycles
- Draft outputs → written as markdown under “outputs/…”
- Evaluation scripts → read outputs and benchmarks from “data/…” → optionally call evaluation LLMs → produce metrics

##### Architectural Patterns & Principles
- Modular separation of concerns: UI, orchestration, tool integration, LLM invocation, data I/O, evaluation
- Plugin architecture for model runners (add new LLMs by implementing a runner)
- Tool‐augmented LLM pattern: agent uses search and navigation tools during generation
- Clear I/O boundaries: JSON/text I/O for data, markdown for outputs, standardized CLI flags

##### Technology Stack
- Python 3.9+
- vLLM for model serving (main & auxiliary)
- Bing Search API (or optional Crawl4AI client) for web crawling
- Streamlit (demo UI)
- lcb_runner framework (runner abstraction)
- Standard libraries & utilities (requests, asyncio, JSON, file I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI1["Run WebThinker CLI"]:::interface
        CLI4["Run Direct Gen CLI"]:::interface
        CLI5["Run Naive RAG CLI"]:::interface
        CLI6["Run Naive RAG Report CLI"]:::interface
        CLI7["Run Search O1 CLI"]:::interface
        CLI2["Run WebThinker Report CLI"]:::interface
        DemoUI["Demo UI"]:::interface
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        OrchestratorPS["Problem-Solving Orchestrator"]:::orchestrator
        OrchestratorRG["Report-Generation Orchestrator"]:::orchestrator
        DemoController["Demo Controller"]:::orchestrator
    end

    %% Tooling & Connectors
    subgraph "Tooling & Connectors"
        WebSearchScript["BingSearch (scripts/search)"]:::tool
        WebSearchDemo["BingSearch (demo)"]:::tool
        PromptsDemo["Prompts (demo)"]:::tool
        PromptsScripts["Prompts (scripts)"]:::tool
        PromptsLCB["Prompts (lcb_runner)"]:::tool
    end

    %% LLM Invocation Layer
    subgraph "LLM Invocation Layer"
        subgraph "lcb_runner Framework"
            BaseRunner["Base Runner"]:::llm
            MainRunner["Main Runner"]:::llm
            OtherRunners["Pluggable Model Runners"]:::llm
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        Benchmarks["Benchmarks & Question Sets"]:::data
        Outputs["Output Storage\n(Markdown Reports)"]:::data
        Figures["Figures"]:::data
    end

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        QA_eval["QA Evaluation Script"]:::eval
        Report_eval["Report Quality Evaluation Script"]:::eval
    end

    %% External Services
    subgraph "External Services"
        BingAPI["Bing Search API"]:::external
        Crawl4AI["Crawl4AI Client (Optional)"]:::external
        LLMService["vLLM & External LLMs"]:::external
    end

    %% Connections
    CLI1 -->|"invoke"| OrchestratorPS
    CLI4 -->|"invoke"| OrchestratorPS
    CLI5 -->|"invoke"| OrchestratorPS
    CLI6 -->|"invoke"| OrchestratorPS
    CLI7 -->|"invoke"| OrchestratorPS
    CLI2 -->|"invoke"| OrchestratorRG
    DemoUI -->|"invoke"| DemoController
    DemoController -->|"control"| OrchestratorPS
    DemoController -->|"control"| OrchestratorRG

    OrchestratorPS -->|"Bing Search API Request"| WebSearchScript
    OrchestratorPS -->|"Bing Search API Request"| WebSearchDemo
    WebSearchScript -->|"API call"| BingAPI
    WebSearchDemo -->|"API call"| BingAPI
    WebSearchScript -->|"optional JS fetch"| Crawl4AI
    WebSearchDemo -->|"optional JS fetch"| Crawl4AI
    WebSearchScript -->|"JSON page content"| OrchestratorPS
    WebSearchDemo -->|"JSON page content"| OrchestratorPS

    OrchestratorPS -->|"use prompts"| PromptsDemo
    OrchestratorPS -->|"use prompts"| PromptsScripts
    OrchestratorPS -->|"use prompts"| PromptsLCB

    OrchestratorPS -->|"LLM Prompt/Response"| BaseRunner
    OrchestratorPS -->|"LLM Prompt/Response"| MainRunner
    BaseRunner -->|"dispatch"| OtherRunners
    MainRunner -->|"dispatch"| OtherRunners
    OtherRunners -->|"model calls"| LLMService
    LLMService -->|"model response"| OtherRunners
    OtherRunners -->|"response"| OrchestratorPS

    OrchestratorPS -->|"write markdown"| Outputs

    OrchestratorRG -->|"LLM Prompt/Response"| BaseRunner
    OrchestratorRG -->|"write markdown"| Outputs

    QA_eval -->|"read"| Outputs
    QA_eval -->|"use benchmarks"| Benchmarks
    QA_eval -->|"LLM call"| LLMService
    QA_eval -->|"produce metrics"| Figures

    Report_eval -->|"read"| Outputs
    Report_eval -->|"use benchmarks"| Benchmarks
    Report_eval -->|"LLM call"| LLMService
    Report_eval -->|"produce metrics"| Figures

    %% Click Events
    click CLI1 "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/run_web_thinker.py"
    click CLI2 "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/run_web_thinker_report.py"
    click CLI4 "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/run_direct_gen.py"
    click CLI5 "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/run_naive_rag.py"
    click CLI6 "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/run_naive_rag_report.py"
    click CLI7 "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/run_search_o1.py"
    click DemoUI "https://github.com/ruc-nlpir/webthinker/blob/main/demo/run_demo.py"
    click DemoController "https://github.com/ruc-nlpir/webthinker/blob/main/demo/run_demo.py"
    click WebSearchScript "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/search/bing_search.py"
    click WebSearchDemo "https://github.com/ruc-nlpir/webthinker/blob/main/demo/bing_search.py"
    click PromptsDemo "https://github.com/ruc-nlpir/webthinker/blob/main/demo/prompts.py"
    click PromptsScripts "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/prompts/prompts.py"
    click PromptsLCB "https://github.com/ruc-nlpir/webthinker/tree/main/scripts/lcb_runner/prompts/"
    click BaseRunner "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/lcb_runner/runner/base_runner.py"
    click MainRunner "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/lcb_runner/runner/main.py"
    click QA_eval "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/evaluate/evaluate.py"
    click Report_eval "https://github.com/ruc-nlpir/webthinker/blob/main/scripts/evaluate/evaluate_report.py"

    %% Styles
    classDef interface fill:#ADD8E6,stroke:#000
    classDef orchestrator fill:#87CEFA,stroke:#000
    classDef tool fill:#90EE90,stroke:#000
    classDef llm fill:#FFA500,stroke:#000
    classDef data fill:#FFFFE0,stroke:#000
    classDef eval fill:#DDA0DD,stroke:#000
    classDef external fill:#F0F0F0,stroke:#000
```
