# assafelovic/gpt-researcher architecture

> Architecture diagram of the GitHub repository assafelovic/gpt-researcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/assafelovic/gpt-researcher
- Repository: https://github.com/assafelovic/gpt-researcher
- Video tour (about a minute): https://gitdiagram.com/assafelovic/gpt-researcher/video

## Overview

#### Overview

GPT Researcher is an AI research application and Python package for producing citation-backed reports from web sources or local documents. Its documented model is planner/execution agents: plan questions, gather sources, summarize and track citations, then aggregate a report. Research can include parallel work, image generation, deep recursive exploration, and multiple report formats.

#### Public Entry Points

- `gpt_researcher/__init__.py`: package-facing API; the README documents `from gpt_researcher import GPTResearcher`, followed by `conduct_research()` and `write_report()`.
- `main.py`: documented FastAPI/ Uvicorn application entry point (`uvicorn main:app`), serving the backend-facing web experience.
- `cli.py`: repository-level command-line entry point area; the tree establishes its existence, but supplied evidence does not define its commands.
- `frontend/nextjs`: production-oriented Next.js application with API routes and research views.
- `multi_agents/main.py`: alternative multi-agent workflow entry point, distinct from the primary package flow.

#### Core Components

- **Research agent and workflow orchestration — `gpt_researcher/agent.py`**  
  Owns the central research-agent surface used by package callers. It coordinates the research task and report-writing capabilities described in the README.

- **Planning, execution, and report generation — `gpt_researcher/actions`**  
  Contains task/query processing, agent creation, retrieval coordination, web scraping actions, markdown processing, and report generation areas. These correspond to the documented planner, execution, summarization, and publisher responsibilities.

- **Search and source adapters — `gpt_researcher/retrievers`**  
  Organizes adapters for numerous search providers and specialized sources, including Tavily, Bing, Google, academic indexes, custom retrievers, and MCP-backed retrieval. These are integration points rather than one mandatory provider.

- **Web acquisition and document extraction — `gpt_researcher/scraper`**  
  Contains browser- and HTTP-oriented scrapers plus handlers for PDFs, JavaScript pages, ArXiv, Firecrawl, and other extraction strategies.

- **Context, documents, and knowledge state — `gpt_researcher/context`**  
  Owns context retrieval/compression concerns. Related document loaders and vector-store concerns are organized under `gpt_researcher/document` and `gpt_researcher/vector_store`; the README states that local documents and memory/context are supported. The supplied evidence does not establish a durable database.

- **Models and runtime configuration — `gpt_researcher/llm_provider`**  
  Provides model-provider areas, including generic LLM and image-generation support. Configuration and environment-backed settings are organized under `gpt_researcher/config`.

- **HTTP, reporting, and realtime server — `backend/server`**  
  Contains the application server, agent discovery, report storage, multi-agent running, and WebSocket management areas. It is the backend boundary for the documented local web deployment.

- **Web client — `frontend/nextjs`**  
  Provides the feature-rich Next.js UI, research pages, settings, report/chat views, and API route surface. The README also documents a separate lightweight frontend served by the backend.

#### Relationships

A caller supplies a query, configuration, optional local-document source, and provider credentials to the research agent. The orchestration layer plans work and delegates source acquisition to retrievers and scrapers; context/document components provide collected material for model processing. The resulting report and citations are returned to the caller or exposed through the backend, with report storage and WebSocket updates supporting the web client.

#### Optional and Alternative Boundaries

`gpt_researcher/mcp` adds caller-configured MCP data sources alongside web retrieval. Image generation is an optional model capability. `deep_agents` provides a separate recursive deep-research implementation, while `multi_agents` contains LangGraph/AG2-style specialized-agent workflows; neither should be assumed to be the default package path.

Main entry points: [`gpt_researcher/actions`](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/actions) (Actions), [`gpt_researcher/agent.py`](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/agent.py) (Research agent), [`gpt_researcher/context`](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/context) (Context), [`backend/server`](https://github.com/assafelovic/gpt-researcher/tree/main/backend/server) (Backend server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research_package["Research package"]
  node_package_api["Package API<br/>Python package entry point<br/>[__init__.py]"]
  node_research_agent["Research agent<br/>workflow orchestrator<br/>[agent.py]"]
  node_actions["Actions<br/>planning and reporting subsystem"]
  node_retrievers["Retrievers<br/>source adapter subsystem"]
  node_scraper["Scraper"]
  node_context["Context"]
  node_documents["Documents<br/>document loader subsystem"]
  node_vector_store[("Vector store<br/>knowledge-state subsystem")]
  node_llm_provider["LLM provider<br/>model provider subsystem"]
  node_config["Configuration"]
  node_mcp{{"MCP sources<br/>optional retrieval integration"}}
end

subgraph group_web_deployment["Web deployment"]
  node_backend["Backend server<br/>FastAPI backend"]
  node_main_entry["Server entry point<br/>FastAPI application entry point<br/>[main.py]"]
  node_frontend["Web client<br/>Next.js application"]
end

node_caller(("Caller<br/>external consumer"))

node_caller -->|"supplies"| node_package_api
node_package_api -->|"exposes"| node_research_agent
node_research_agent -->|"orchestrates"| node_actions
node_actions -->|"delegates"| node_retrievers
node_actions -->|"delegates"| node_scraper
node_context -->|"provides context"| node_actions
node_documents -->|"supplies documents"| node_context
node_vector_store -->|"supports"| node_context
node_llm_provider -->|"supports processing"| node_actions
node_config -->|"configures"| node_research_agent
node_mcp -.->|"extends"| node_retrievers
node_main_entry -->|"starts"| node_backend
node_research_agent -->|"exposes reports through"| node_backend
node_frontend -->|"uses"| node_backend

click node_package_api "https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/__init__.py"
click node_research_agent "https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/agent.py"
click node_actions "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/actions"
click node_retrievers "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/retrievers"
click node_scraper "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/scraper"
click node_context "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/context"
click node_documents "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/document"
click node_vector_store "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/vector_store"
click node_llm_provider "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/llm_provider"
click node_config "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/config"
click node_backend "https://github.com/assafelovic/gpt-researcher/tree/main/backend/server"
click node_main_entry "https://github.com/assafelovic/gpt-researcher/blob/main/main.py"
click node_frontend "https://github.com/assafelovic/gpt-researcher/tree/main/frontend/nextjs"
click node_mcp "https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/mcp"

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_package_api,node_research_agent,node_actions,node_retrievers,node_scraper,node_context,node_documents,node_vector_store,node_llm_provider,node_config,node_mcp toneBlue
class node_backend,node_main_entry,node_frontend toneAmber
class node_caller toneNeutral
```

## Components

### Research package

Core planning, acquisition, processing, and model capabilities.

- [Package API](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/__init__.py): Python package entry point · Exposes GPTResearcher to package callers. · `gpt_researcher/__init__.py`
- [Research agent](https://github.com/assafelovic/gpt-researcher/blob/main/gpt_researcher/agent.py): workflow orchestrator · Coordinates research and report writing. · `gpt_researcher/agent.py`
- [Actions](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/actions): planning and reporting subsystem · Plans tasks, retrieves material, summarizes results, and generates reports. · `gpt_researcher/actions`
- [Retrievers](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/retrievers): source adapter subsystem · Provides search-provider and specialized-source integrations. · `gpt_researcher/retrievers`
- [Scraper](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/scraper): web and document acquisition subsystem · Extracts content from web pages and documents. · `gpt_researcher/scraper`
- [Context](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/context): context and memory subsystem · Retrieves and compresses research context. · `gpt_researcher/context`
- [Documents](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/document): document loader subsystem · Supports local-document research inputs. · `gpt_researcher/document`
- [Vector store](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/vector_store): knowledge-state subsystem · Supports vector-store concerns for context and documents. · `gpt_researcher/vector_store`
- [LLM provider](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/llm_provider): model provider subsystem · Provides language-model and optional image-generation capabilities. · `gpt_researcher/llm_provider`
- [Configuration](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/config): runtime configuration subsystem · Organizes environment-backed settings. · `gpt_researcher/config`
- [MCP sources](https://github.com/assafelovic/gpt-researcher/tree/main/gpt_researcher/mcp): optional retrieval integration · Adds caller-configured MCP data sources. · `gpt_researcher/mcp`

### Web deployment

Backend and frontend surfaces for web-based research.

- [Backend server](https://github.com/assafelovic/gpt-researcher/tree/main/backend/server): FastAPI backend · Provides application serving, report storage, agent running, and WebSocket management. · `backend/server`
- [Server entry point](https://github.com/assafelovic/gpt-researcher/blob/main/main.py): FastAPI application entry point · Runs the documented Uvicorn application. · `main.py`
- [Web client](https://github.com/assafelovic/gpt-researcher/tree/main/frontend/nextjs): Next.js application · Provides research views, settings, reports, chat, and API routes. · `frontend/nextjs`

### Other components

- **Caller**: external consumer · Supplies queries, configuration, credentials, and optional local documents.

## Connections

- Caller → Package API: supplies · The caller supplies the research request and inputs.
- Package API → Research agent: exposes · The package API exposes GPTResearcher.
- Research agent → Actions: orchestrates · The research agent coordinates planning and report-writing actions.
- Actions → Retrievers: delegates · Actions delegate source acquisition to retrievers.
- Actions → Scraper: delegates · Actions delegate web and document extraction to scrapers.
- Context → Actions: provides context · Context components provide collected material for model processing.
- Documents → Context: supplies documents · Document loaders support local-document context.
- Vector store → Context: supports · Vector-store concerns support context retrieval.
- LLM provider → Actions: supports processing · Model providers support summarization and report generation.
- Configuration → Research agent: configures · Runtime settings configure the research workflow.
- MCP sources → Retrievers: extends · MCP adds caller-configured sources alongside web retrieval.
- Server entry point → Backend server: starts · The FastAPI entry point starts the backend application.
- Research agent → Backend server: exposes reports through · Research results and citations are exposed through the backend.
- Web client → Backend server: uses · The web client uses backend APIs and realtime services.
