node-deepresearch

To install the DeepResearch codebase locally, clone the repository and install the dependencies using npm.

git clone https://github.com/jina-ai/node-DeepResearch.git
cd node-DeepResearch
npm install

To use a local LLM instead of a cloud provider, redirect the reasoning requests by setting the LLM_PROVIDER to openai and configuring the OPENAI_BASE_URL to point to your local endpoint. Note that the LLM must support structured output (JSON Schema/object output) for the reasoning flow to work.

export LLM_PROVIDER=openai
export OPENAI_BASE_URL=http://127.0.0.1:1234/v1
export OPENAI_API_KEY=whatever
export DEFAULT_MODEL_NAME=qwen2.5-7b

export LLM_PROVIDER=openai  # yes, that's right - for local llm we still use openai client
export OPENAI_BASE_URL=http://127.0.0.1:1234/v1  # your local llm endpoint
export OPENAI_API_KEY=whatever  # random string would do, as we don't use it (unless your local LLM has authentication)
export DEFAULT_MODEL_NAME=qwen2.5-7b  # your local llm model name

You can run the DeepResearch agent directly from the command line by providing a query. You must set up the required environment variables for your LLM provider (Gemini or OpenAI) and your Jina API key.

Required Environment Variables:

• GEMINI_API_KEY (if using Gemini)
• OPENAI_API_KEY (if using OpenAI)
• LLM_PROVIDER (set to openai if using OpenAI)
• JINA_API_KEY (get from https://jina.ai/reader)

Execution:

npm run dev "your query here"

export GEMINI_API_KEY=...  # for gemini
# export OPENAI_API_KEY=... # for openai
# export LLM_PROVIDER=openai # for openai
export JINA_API_KEY=jina_...  # free jina api key, get from https://jina.ai/reader

npm run dev "your query here"

You can run the project as a local server that provides an OpenAI-compatible /v1/chat/completions endpoint. This allows you to connect GUI clients like CherryStudio or Chatbox.

Start the server:

• Without authentication: npm run serve
• With authentication: npm run serve --secret=your_secret_token (clients must provide this as a Bearer token).

The server defaults to http://localhost:3000.

Example Request (Authenticated):

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_token" \
  -d '{
    "model": "jina-deepsearch-v1",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

# Without authentication
npm run serve

# With authentication (clients must provide this secret as Bearer token)
npm run serve --secret=your_secret_token

You can containerize the application using Docker.

Build the image:

docker build -t deepresearch:latest .

Run the container:

docker run -p 3000:3000 --env GEMINI_API_KEY=your_gemini_api_key --env JINA_API_KEY=your_jina_api_key deepresearch:latest

Using Docker Compose:

docker-compose up

DeepResearch supports multiple LLM providers. You must set the LLM_PROVIDER environment variable and provide the corresponding API key(s).

Supported Providers:

• openai: Requires OPENAI_API_KEY. You can optionally set OPENAI_BASE_URL for custom endpoints.
• gemini: Requires GEMINI_API_KEY.
• vertex: Requires GCLOUD_PROJECT and uses Google Vertex AI settings.

Required Keys for all providers:

• JINA_API_KEY is required regardless of the LLM provider selected.

When running node-deepresearch via Docker Compose, you must provide the following environment variables in your host environment or a .env file to enable different AI providers and search capabilities:

• GEMINI_API_KEY: API key for Google Gemini.
• OPENAI_API_KEY: API key for OpenAI.
• JINA_API_KEY: API key for Jina AI services.
• BRAVE_API_KEY: API key for Brave Search.

The application service maps port 3000 on the host to port 3000 in the container.

services:
  app:
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - JINA_API_KEY=${JINA_API_KEY}
      - BRAVE_API_KEY=${BRAVE_API_KEY}
    ports:
      - "3000:3000"

You can configure search providers and network proxy settings via environment variables:

• BRAVE_API_KEY: API key for Brave search.
• SERPER_API_KEY: API key for Serper search.
• https_proxy: Set this to a proxy URL (e.g., http://proxy.example.com:8080) to route all outgoing requests through a proxy using undici's ProxyAgent.

The project uses several interfaces for handling search and web content retrieval:

• JinaSearchResponse: Standard Jina search output with results (title, snippet, url) and meta (query, num_results, latency, credits).
• SearchResponse: Generic search response containing code, status, and data (array of title, description, url, content, and usage).
• ReadResponse: Response from reading a specific URL, including links (array of [anchor, url]) and images (record of image: url).
• WebContent: Represents parsed web content with full text, chunks (string array), and chunk_positions (array of index arrays).