An AI-powered research assistant that performs iterative, deep research on any topic by combining search engines, web scraping, and large language models.

The goal of this repo is to provide the simplest implementation of a deep research agent - e.g. an agent that can refine its research direction over time and deep dive into a topic. Goal is to keep the repo size at <500 LoC so it is easy to understand and build on top of.

Loading

Iterative Research: Performs deep research by iteratively generating search queries, processing results, and diving deeper based on findings

Intelligent Query Generation: Uses LLMs to generate targeted search queries based on research goals and previous findings

Depth & Breadth Control: Configurable parameters to control how wide (breadth) and deep (depth) the research goes

Smart Follow-up: Generates follow-up questions to better understand research needs

Comprehensive Reports: Produces detailed markdown reports with findings and sources

Concurrent Processing: Handles multiple searches and result processing in parallel for efficiency

Node.js environment

API keys for:

Clone the repository

Install dependencies:

Set up environment variables in a .env.local file:

To use local LLM, comment out OPENAI_KEY and instead uncomment OPENAI_ENDPOINT and OPENAI_MODEL:

Set OPENAI_ENDPOINT to the address of your local server (eg."http://localhost:1234/v1")

Set OPENAI_MODEL to the name of the model loaded in your local server.

Clone the repository

Rename .env.example to .env.local and set your API keys

Run docker build -f Dockerfile

Run the Docker image:

Execute npm run docker in the docker service:

Run the research assistant:

You'll be prompted to:

Enter your research query

Specify research breadth (recommended: 3-10, default: 4)

Specify research depth (recommended: 1-5, default: 2)

Answer follow-up questions to refine the research direction

The system will then:

Generate and execute search queries

Process and analyze search results

Recursively explore deeper based on findings

Generate a comprehensive markdown report

The final report will be saved as report.md or answer.md in your working directory, depending on which modes you selected.

If you have a paid version of Firecrawl or a local version, feel free to increase the ConcurrencyLimit by setting the CONCURRENCY_LIMIT environment variable so it runs faster.

If you have a free version, you may sometimes run into rate limit errors, you can reduce the limit to 1 (but it will run a lot slower).

Deep research performs great on R1! We use Fireworks as the main provider for the R1 model. To use R1, simply set a Fireworks API key:

The system will automatically switch over to use R1 instead of o3-mini when the key is detected.

There are 2 other optional env vars that lets you tweak the endpoint (for other OpenAI compatible APIs like OpenRouter or Gemini) as well as the model string.

MIT License - feel free to use and modify as needed.