deep-research README

The project's README from github.com/dzhng/deep-research. As one markdown file: README.md.

Open Deep Research

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.

If you like this project, please consider starring it and giving me a follow on X/Twitter. This project is created by Duet.

How It Works

flowchart TB
    subgraph Input
        Q[User Query]
        B[Breadth Parameter]
        D[Depth Parameter]
    end

    DR[Deep Research] -->
    SQ[SERP Queries] -->
    PR[Process Results]

    subgraph Results[Results]
        direction TB
        NL((Learnings))
        ND((Directions))
    end

    PR --> NL
    PR --> ND

    DP{depth > 0?}

    RD["Next Direction:
    - Prior Goals
    - New Questions
    - Learnings"]

    MR[Markdown Report]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|Yes| RD
    RD -->|New Context| DR

    %% Final Output
    DP -->|No| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ,PR process
    class DP,RD recursive
    class MR output
    class NL,ND results

Features

Requirements

Setup

Node.js

  1. Clone the repository
  2. Install dependencies:
npm install
  1. Set up environment variables in a .env.local file:
FIRECRAWL_KEY="your_firecrawl_key"
# If you want to use your self-hosted Firecrawl, add the following below:
# FIRECRAWL_BASE_URL="http://localhost:3002"

OPENAI_KEY="your_openai_key"

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

Docker

  1. Clone the repository

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

  3. Run docker build -f Dockerfile

  4. Run the Docker image:

docker compose up -d
  1. Execute npm run docker in the docker service:
docker exec -it deep-research npm run docker

Usage

Run the research assistant:

npm start

You'll be prompted to:

  1. Enter your research query
  2. Specify research breadth (recommended: 3-10, default: 4)
  3. Specify research depth (recommended: 1-5, default: 2)
  4. Answer follow-up questions to refine the research direction

The system will then:

  1. Generate and execute search queries
  2. Process and analyze search results
  3. Recursively explore deeper based on findings
  4. 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.

Concurrency

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).

DeepSeek R1

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:

FIREWORKS_KEY="api_key"

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

Custom endpoints and models

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.

OPENAI_ENDPOINT="custom_endpoint"
CUSTOM_MODEL="custom_model"

How It Works

  1. Initial Setup

    • Takes user query and research parameters (breadth & depth)
    • Generates follow-up questions to understand research needs better

  2. Deep Research Process

    • Generates multiple SERP queries based on research goals
    • Processes search results to extract key learnings
    • Generates follow-up research directions

  3. Recursive Exploration

    • If depth > 0, takes new research directions and continues exploration
    • Each iteration builds on previous learnings
    • Maintains context of research goals and findings

  4. Report Generation

    • Compiles all findings into a comprehensive markdown report
    • Includes all sources and references
    • Organizes information in a clear, readable format

Community implementations

Python: https://github.com/Finance-LLMs/deep-research-python

License

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

deep-research (dzhng/deep-research)

Searching Database…

19.8K ·GitHub
Deep-research
Что это такое?ИИ-помощник для исследований, который глубоко разбирается в любой теме: он объединяет поисковые системы, парсинг веб-страниц и большие языковые модели, постепенно уточняя направление исследования.
Это приложение, которое я запускаю, или библиотека, которую я добавляю в свой проект?Это запускаемое приложение на TypeScript, а не библиотека: npm start запускает исследовательскую сессию в терминале, а npm run api поднимает API-сервер на Express. Код намеренно небольшой, чтобы вы могли его дорабатывать.
Как его запустить?Склонируйте репозиторий, выполните npm install, положите свои API-ключи в файл .env.local, затем запустите npm start для работы в терминале или npm run api для сервера. Требуется Node.js 22.
Что нужно установить заранее, чтобы всё заработало?Node.js 22.x плюс API-ключи: запросы к LLM идут через Vercel AI SDK с адаптерами OpenAI и Fireworks, а для парсинга веб-страниц нужен ключ Firecrawl.
Есть ли подводные камни, о которых стоит знать заранее?Автор ставил целью сделать максимально простой агент для глубоких исследований, а не отполированный продукт — тестов пока нет (тестовый скрипт — заглушка), так что рассчитывайте на компактную кодовую базу для развития.
Он работает на Windows и Mac или только на Linux?Это обычное приложение на Node.js, поэтому оно работает везде, где работает Node 22 — на macOS, Windows или Linux.
Можно ли запустить его на своём сервере?Да — в репозитории есть Dockerfile и настройка docker-compose, так что вы можете запустить его в контейнере на любом своём сервере.
Ему всё время нужно быть онлайн?Да — каждый шаг идёт через облачные сервисы: веб-поиск, парсинг через Firecrawl и вызовы API LLM, поэтому офлайн-режима нет.
Можно ли свободно использовать и менять его в своих проектах?Да — лицензия MIT: можно свободно использовать и изменять, в том числе в коммерческих целях; учтите только, что API для LLM и парсинга могут быть платными.
Как выглядит итоговый результат?Подробный отчёт в формате markdown, где собраны все результаты, указаны все источники и ссылки, и всё разложено по понятной и читаемой структуре.
Как он решает, что исследовать дальше?Он работает циклами: на каждой итерации выбирает новые направления исследования на основе уже найденного, сохраняя контекст целей и выводов, поэтому может постепенно углубляться в тему.
Есть ли версия на Python?Да — в README перечислены реализации от сообщества, включая версию агента на Python, так что вы не привязаны к TypeScript.
What are similar projects?gpt-crawler, canonry, Raven, wigolo, deer-flow, ChatDev, DeepAnalyze, trueforge
Which topics is it in?deep-research, search-engine, express, gpt, web-scraping, openai, research, agent, api, ai-agents, tool, llm
Creator
dzhng
Size
0.1 MB
Stars
19.8K
Updated
CommitApr 11
Age
1y
Commits · 90 Days