### Install DeepResearch Project

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Clone the repository, navigate to the directory, and install dependencies using npm. This is the recommended installation method.

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

--------------------------------

### Example: Boost News Sources with URL Filtering

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

This example uses `boost_hostnames` to increase the ranking of results from news sources like `news.ycombinator.com` and `bbc.com` when searching for the latest tech news.

```bash
curl ... -d '{
  "boost_hostnames": ["news.ycombinator.com", "bbc.com"],
  "messages": [{"role": "user", "content": "latest tech news"}]
}'
```

--------------------------------

### Docker Setup

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Instructions for building and running the application using Docker and Docker Compose.

```APIDOC
## Docker Setup

### Build Docker Image
To build the Docker image for the application, run the following command:

```bash
docker build -t deepresearch:latest .
```

### Run Docker Container
To run the Docker container, use the following command:

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

### Docker Compose
You can also use Docker Compose to manage multi-container applications. To start the application with Docker Compose, run:

```bash
docker-compose up
```
```

--------------------------------

### Example: Academic-Focused Research with URL Filtering

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

This example uses `only_hostnames` to restrict results to academic domains like `arxiv.org` and `edu` for research on quantum computing.

```bash
curl ... -d '{
  "only_hostnames": ["arxiv.org", "scholar.google.com", "edu"],
  "messages": [{"role": "user", "content": "quantum computing papers"}]
}'
```

--------------------------------

### Local LLM Setup

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Instructions on how to configure the application to use a local LLM provider like Ollama or LMStudio.

```APIDOC
## Use Local LLM

> Note, not every LLM works with our reasoning flow, we need those who support structured output (sometimes called JSON Schema output, object output) well. Feel free to purpose a PR to add more open-source LLMs to the working list.

If you use Ollama or LMStudio, you can redirect the reasoning request to your local LLM by setting the following environment variables:

```bash
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
```
```

--------------------------------

### Example Token Budget Configuration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Illustrates setting a high reasoning effort with custom token budget and max attempts.

```json
{
  "model": "jina-deepsearch-v1",
  "messages": [...],
  "reasoning_effort": "high",
  "budget_tokens": 2000000,
  "max_attempts": 5
}
```

--------------------------------

### Start OpenAI-Compatible Server

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Start the Jina AI Deep Research server, which provides an OpenAI-compatible API. You can start it with or without authentication.

```bash
npm run serve
```

```bash
npm run serve --secret=your_secret_token
```

--------------------------------

### Example: Exclude Low-Quality Domains with URL Filtering

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

This example uses `bad_hostnames` to exclude potentially low-quality domains like `quora.com` and `reddit.com` when searching for medical advice.

```bash
curl ... -d '{
  "bad_hostnames": ["quora.com", "reddit.com"],
  "messages": [{"role": "user", "content": "medical advice"}]
}'
```

--------------------------------

### Serve HTTP API with Authentication

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Start the HTTP server with authentication enabled. Requires a secret token for access.

```bash
npm run serve --secret=token
```

--------------------------------

### Example Response for /v1/models

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/02-api-reference-endpoints.md

This JSON response lists the available models, including their IDs, creation timestamps, and ownership.

```json
{
  "object": "list",
  "data": [
    {
      "id": "jina-deepsearch-v1",
      "object": "model",
      "created": 1686935002,
      "owned_by": "jina-ai"
    },
    {
      "id": "jina-deepsearch-v2",
      "object": "model",
      "created": 1717987200,
      "owned_by": "jina-ai"
    }
  ]
}
```

--------------------------------

### Serve HTTP API

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Start the HTTP server for API access. This is used for integrating with clients or other services.

```bash
npm run serve
```

--------------------------------

### Example Usage of ActionTracker

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Demonstrates how to instantiate and use the ActionTracker to simulate agent actions. It shows how to track a search action and how the event listener processes it.

```typescript
const tracker = new ActionTracker();

tracker.on('action', (step) => {
  if (step.action === 'search') {
    console.log('Searching for:', step.searchRequests);
  }
  if (step.action === 'visit') {
    console.log('Visiting URLs:', step.URLTargets);
  }
  if (step.action === 'answer') {
    console.log('Answer:', step.answer);
  }
});

tracker.trackAction({
  thisStep: { action: 'search', searchRequests: ['AI news'], think: 'searching...' }
});
```

--------------------------------

### Run Development Server in CLI Mode

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Start the application in CLI mode for manual testing or development. Allows passing a query directly.

```bash
npm run dev "your query"
```

--------------------------------

### Start Server with Secret

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/02-api-reference-endpoints.md

Starts the Node Deepresearch server with an optional authentication secret. If a secret is provided, all requests must include an 'Authorization: Bearer TOKEN' header.

```bash
npm run serve --secret=my_secret_token
```

--------------------------------

### Model Configuration Override Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Demonstrates how to override specific model parameters like temperature and maxTokens for certain tools, while inheriting others from the default.

```json
{
  "gemini": {
    "default": {
      "model": "gemini-2.0-flash",
      "temperature": 0.7,
      "maxTokens": 4000
    },
    "tools": {
      "evaluator": {
        "temperature": 1.0
      },
      "agent": {
        "maxTokens": 8000
      }
    }
  }
}
```

--------------------------------

### Example Usage of TokenTracker

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Demonstrates how to instantiate and use the TokenTracker to track LLM token usage for different tools. Shows how to track usage, retrieve total usage, and access usage breakdown.

```typescript
const tracker = new TokenTracker(100000);  // 100k token budget

tracker.trackUsage('search', {
  promptTokens: 50,
  completionTokens: 100,
  totalTokens: 150
});

const total = tracker.getTotalUsage();
console.log(total.totalTokens);  // 150

const breakdown = tracker.getUsageBreakdown();
console.log(breakdown['search']);  // 150
```

--------------------------------

### 404 Not Found Fix Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This JSON object shows how to specify a valid model name to resolve a 404 Not Found error.

```json
{ "model": "jina-deepsearch-v1" }
```

--------------------------------

### Example Chat Completion Request

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/02-api-reference-endpoints.md

Use this snippet to make a standard chat completion request. Ensure the 'model' and 'messages' fields are correctly populated.

```bash
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-deepsearch-v1",
    "messages": [
      { "role": "user", "content": "What is the latest Jina AI news?" }
    ],
    "stream": false
  }'
```

--------------------------------

### Example Error Response

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/02-api-reference-endpoints.md

This is the standard JSON format for error responses from the API. It includes a description of the error encountered.

```json
{
  "error": "error message description"
}
```

--------------------------------

### Proxy Agent Setup

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/03-api-reference-agent.md

Configures a global proxy agent if the https_proxy environment variable is set. This affects the undici HTTP client globally.

```typescript
const dispatcher = new ProxyAgent({ uri: process.env.https_proxy });
setGlobalDispatcher(dispatcher);  // Applied globally to undici HTTP client
```

--------------------------------

### Docker Compose Up Command

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Use Docker Compose to start the Jina AI Deep Research application and any associated services. This simplifies multi-container application management.

```bash
docker-compose up
```

--------------------------------

### Example Streaming Chat Completion Request

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/02-api-reference-endpoints.md

This snippet demonstrates how to initiate a streaming chat completion request. Include an 'Authorization' header if your server requires a secret token.

```bash
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": "Who is the CEO of OpenAI?" }
    ],
    "stream": true
  }'
```

--------------------------------

### 404 Not Found Response Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This JSON response indicates that a requested model was not found. It provides details about the error, including the model name and type.

```json
{
  "error": {
    "message": "Model 'gpt-4' not found",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}
```

--------------------------------

### Configure Response and Search Language

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Set `language_code` for response and prompt language, and `search_language_code` for search query language. The example shows researching in English while searching German sources.

```json
{
  "language_code": "en",
  "search_language_code": "en"
}
```

```json
{
  "language_code": "en",
  "search_language_code": "de",
  "messages": [{"role": "user", "content": "German tech innovations"}]
}
```

--------------------------------

### Run Docker Integration Tests

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Execute tests that require a Docker environment. This is used to verify functionality in a containerized setup.

```bash
npm run test:docker
```

--------------------------------

### Retry Logic Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

Demonstrates a basic retry mechanism for API calls. It checks if an error is retryable and retries once after a backoff period.

```typescript
try {
  result = await apiCall();
} catch (error) {
  if (isRetryable(error)) {
    await wait(backoffMs);
    result = await apiCall();  // Retry once
  } else {
    throw error;
  }
}
```

--------------------------------

### Get Agent Response

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/03-api-reference-agent.md

Demonstrates how to call the getResponse function with various parameters to obtain an answer to a question. This includes setting token budgets, attempt limits, and search preferences.

```typescript
import { getResponse } from './agent';
import { TokenTracker } from './utils/token-tracker';
import { ActionTracker } from './utils/action-tracker';
import { TrackerContext } from './types';

const context: TrackerContext = {
  tokenTracker: new TokenTracker(),
  actionTracker: new ActionTracker()
};

const result = await getResponse(
  'What is the capital of France?',
  100000,  // 100k token budget
  2,       // max 2 bad attempts
  context,
  [{ role: 'user', content: 'What is the capital of France?' }],
  10,      // max 10 URLs
  false,   // don't skip direct answer
  [],      // no boosted domains
  [],      // no bad domains
  [],      // no hostname whitelist
  10,      // max 10 annotations
  0.7,     // min relevance 0.7
  'en',    // English
  'en',    // search in English
  'jina',  // use Jina search
  false    // no images
);

console.log(result.result.mdAnswer);
console.log('Visited URLs:', result.visitedURLs);
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Define and run multi-container Docker applications using Docker Compose. This example sets up the deepresearch service with environment variables and restart policy.

```yaml
version: '3.8'
services:
  deepresearch:
    image: deepresearch:latest
    ports:
      - '3000:3000'
    environment:
      GEMINI_API_KEY: ${GEMINI_API_KEY}
      JINA_API_KEY: ${JINA_API_KEY}
      LLM_PROVIDER: gemini
      SEARCH_PROVIDER: jina
      PORT: 3000
    restart: unless-stopped
```

--------------------------------

### 401 Unauthorized Fix Example (cURL)

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This cURL command demonstrates how to fix a 401 Unauthorized error by including the Authorization header with a bearer token.

```bash
curl -H "Authorization: Bearer YOUR_SECRET_TOKEN" ...
```

--------------------------------

### Handle Search Provider Failure

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

Example of a JSON error response from a search provider indicating a rate limit exceeded error.

```json
{
  "error": "Search failed",
  "provider": "jina",
  "statusCode": 429,
  "message": "Rate limit exceeded"
}
```

--------------------------------

### Interact with OpenAI-Compatible Server API

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Use curl to send POST requests to the /v1/chat/completions endpoint of the running server. Examples are provided for both authenticated and unauthenticated requests.

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

```bash
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
  }'
```

--------------------------------

### HTTP Client with Axios

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

A configured axios instance for making HTTP requests, featuring retry, timeout, and proxy support. Demonstrates basic GET and POST request usage.

```typescript
import axiosClient from './utils/axios-client';

// Configured axios instance with retry, timeout, proxy support
const response = await axiosClient.get(url, config);
const result = await axiosClient.post(url, data, config);
```

--------------------------------

### Docker Compose Environment Variables

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Configure environment variables for a Docker Compose setup, including API keys, port, and LLM provider.

```yaml
environment:
  - GEMINI_API_KEY=${GEMINI_API_KEY}
  - JINA_API_KEY=${JINA_API_KEY}
  - PORT=3000
  - LLM_PROVIDER=gemini
```

--------------------------------

### Render Streaming Response in Web UI

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Integrate Jina DeepSearch with a web UI to display streaming responses in real-time. This example shows how to handle thinking steps and final answers separately.

```html
<div id="thinking"><!-- Thinking steps appear here --></div>
<div id="answer"><!-- Final answer appears here --></div>

<script>
const response = await fetch('http://localhost:3000/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'jina-deepsearch-v1',
    messages: [{ role: 'user', content: userQuery }],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let inThinking = false;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  const lines = text.split('\n');
  
  for (const line of lines) {
    if (!line.startsWith('data: ')) continue;
    
    const chunk = JSON.parse(line.slice(6));
    const delta = chunk.choices[0]?.delta;
    
    if (delta.content === '<think>') {
      inThinking = true;
    } else if (delta.content === '</think>') {
      inThinking = false;
    } else if (delta.content) {
      const target = inThinking ? '#thinking' : '#answer';
      document.querySelector(target).textContent += delta.content;
    }
  }
}
</script>
```

--------------------------------

### Python OpenAI Client Integration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Integrate DeepResearch with Python applications using the OpenAI SDK. Configure the API key and base URL for communication. This example demonstrates a non-streaming chat completion.

```python
from openai import OpenAI

client = OpenAI(
    api_key='your-secret-token',
    base_url='http://localhost:3000/v1'
)

response = client.chat.completions.create(
    model='jina-deepsearch-v1',
    messages=[
        {'role': 'user', 'content': 'What are the latest AI breakthroughs?'}
    ],
    stream=False
)

print(response.choices[0].message.content)
print('URLs:', response.visited_urls)
```

--------------------------------

### Build and Run Docker Image

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Build a Docker image for the application and run it as a container. Ensure to set necessary environment variables.

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist ./dist
EXPOSE 3000
ENV NODE_ENV=production
CMD ["node", "dist/server.js"]
```

```bash
docker build -t deepresearch:latest .
docker run -p 3000:3000 \
  -e GEMINI_API_KEY=AIza... \
  -e JINA_API_KEY=jina_... \
  -e PORT=3000 \
  deepresearch:latest
```

--------------------------------

### 500 Internal Server Error Streaming Response Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This example shows an error message within a streaming response, indicated by 'event: close' and a data payload with a 'type': 'error' field.

```text
event: close
data: {
  "choices": [{
    "delta": { "content": "Error message", "type": "error" },
    "finish_reason": "error"
  }],
  "usage": { ... }
}
```

--------------------------------

### /v1/models/:model

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Get details for a specific model.

```APIDOC
## GET /v1/models/:model

### Description
Get details for a specific model.

### Method
GET

### Endpoint
/v1/models/:model

### Parameters
#### Path Parameters
- **model** (string) - Required - The name of the model.
```

--------------------------------

### Run Development Server with Queries

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Execute the development server with different types of queries, ranging from simple calculations to complex research questions. Some queries may result in multi-step reasoning.

```bash
npm run dev "1+1="
```

```bash
npm run dev "what is the capital of France?"
```

```bash
npm run dev "what is the latest news from Jina AI?"
```

```bash
npm run dev "what is the twitter account of jina ai's founder"
```

```bash
npm run dev "who is bigger? cohere, jina ai, voyage?"
```

```bash
npm run dev "who will be president of US in 2028?"
```

```bash
npm run dev "what should be jina ai strategy for 2025?"
```

--------------------------------

### Main Agent Function

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/INDEX.txt

The primary function for interacting with the agent to get a response.

```APIDOC
## getResponse()

### Description
Provides the main agent functionality to generate a response based on input.

### Method
Not specified (likely a function call).

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### LLM Model Configuration Structure

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Illustrates how to configure LLM models, temperatures, and token limits per provider and tool.

```json
{
  "models": {
    "gemini": {
      "default": { "model": "gemini-2.0-flash", "temperature": 0.7, "maxTokens": 4000 },
      "tools": {
        "agent": { "model": "gemini-2.0-flash", "temperature": 0.7, "maxTokens": 4000 },
        "evaluator": { "temperature": 1.0 },
        "finalizer": { "temperature": 0.7 },
        "research_planner": { "temperature": 0.7 },
        "serp_cluster": { "temperature": 0.7 },
        "reducer": { "temperature": 0.7 },
        "error_analyzer": { "temperature": 0.7 },
        "research_plan": { "temperature": 0.7 }
      }
    },
    "openai": {
      "default": { "model": "gpt-4o-mini", "temperature": 0.7, "maxTokens": 4000 },
      "tools": { ... }
    }
  }
}
```

--------------------------------

### formatDateRange()

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Formats a start and end date into a human-readable string representing a date range, with optional language code customization.

```APIDOC
## formatDateRange()

### Description
Formats a date range as human-readable string.

### Signature
```typescript
export function formatDateRange(
  startDate: string,
  endDate: string,
  languageCode?: string
): string
```
```

--------------------------------

### Configure Local LLM with Environment Variables

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Set environment variables to use a local LLM provider like Ollama or LMStudio. Ensure `LLM_PROVIDER` is set to `openai`, provide the local base URL, a dummy API key, and specify your local model name.

```bash
export LLM_PROVIDER=openai
export OPENAI_BASE_URL=http://127.0.0.1:1234/v1
export OPENAI_API_KEY=whatever  # Can be dummy value
export DEFAULT_MODEL_NAME=qwen2.5-7b  # Your local model name
```

--------------------------------

### Format Date Range as String

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Formats a start and end date into a human-readable string, suitable for displaying time periods.

```typescript
export function formatDateRange(
  startDate: string,
  endDate: string,
  languageCode?: string
): string
```

--------------------------------

### Configure Local LLM with Environment Variables

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Set environment variables to redirect reasoning requests to a local LLM provider like Ollama or LMStudio. Ensure your local LLM supports structured output.

```bash
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
```

--------------------------------

### OpenAI Model Configuration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Configure the default model, temperature, and maximum tokens for OpenAI. 'gpt-4o-mini' is recommended for its speed and cost-effectiveness.

```json
{
  "models": {
    "openai": {
      "default": {
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "maxTokens": 4000
      }
    }
  }
}
```

--------------------------------

### Root Keys of config.json

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Shows the main sections available in the root of the configuration file.

```json
{
  "env": { ... },
  "defaults": { ... },
  "providers": { ... },
  "models": { ... }
}
```

--------------------------------

### Deploy to Cloud Run

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Deploy the application to Google Cloud Run. This command deploys from source, sets environment variables, and configures a timeout.

```bash
gcloud run deploy deepresearch \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GEMINI_API_KEY=$GEMINI_API_KEY,JINA_API_KEY=$JINA_API_KEY \
  --timeout 600
```

--------------------------------

### 401 Unauthorized Response Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This JSON response signifies an authentication failure. It suggests providing a valid API key or token in the Authorization header.

```json
{
  "error": "Unauthorized. Please provide a valid Jina API key."
}
```

--------------------------------

### OpenAI-Compatible Server API

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Details on running the server and interacting with the OpenAI-Compatible API endpoint for chat completions.

```APIDOC
## OpenAI-Compatible Server API

If you have a GUI client that supports OpenAI API (e.g. [CherryStudio](https://docs.cherry-ai.com/), [Chatbox](https://github.com/Bin-Huang/chatbox)), you can simply config it to use this server.

![demo1](.github/visuals/demo6.gif)

Start the server:

```bash
# Without authentication
npm run serve

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

The server will start on http://localhost:3000 with the following endpoint:

### POST /v1/chat/completions

```bash
# Without authentication
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-deepsearch-v1",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

# With authentication (when server is started with --secret)
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
  }'
```

Response format:

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "jina-deepsearch-v1",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "YOUR FINAL ANSWER"
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}
```

For streaming responses (stream: true), the server sends chunks in this format:

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion.chunk",
  "created": 1694268190,
  "model": "jina-deepsearch-v1",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "..."
    },
    "logprobs": null,
    "finish_reason": null
  }]
}
```

Note: The think content in streaming responses is wrapped in XML tags:

```
<think>
[thinking steps...]
</think>
[final answer]
```
```

--------------------------------

### Docker Build Command

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Build the Docker image for the Jina AI Deep Research application using the provided command. This creates a tagged image for deployment.

```bash
docker build -t deepresearch:latest .
```

--------------------------------

### Multi-Turn Conversation Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Pass the full conversation history in the `messages` array for multi-turn interactions. DeepResearch automatically extracts this as 'chat-history' knowledge items.

```typescript
const messages = [
  { role: 'user', content: 'What is machine learning?' },
  { role: 'assistant', content: 'Machine learning is...' },
  { role: 'user', content: 'How is it different from deep learning?' }
];

const response = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages,
  stream: false
});
```

--------------------------------

### /v1/models

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

List available models.

```APIDOC
## GET /v1/models

### Description
List available models.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- (No specific fields documented)
```

--------------------------------

### 500 Internal Server Error Response Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This JSON response indicates an unexpected internal server error during processing. It includes a request ID for tracking.

```json
{
  "id": "request-id",
  "object": "chat.completion",
  "error": "Internal server error during research loop"
}
```

--------------------------------

### Get Model Details

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/02-api-reference-endpoints.md

Retrieves details for a specific model using its ID. Expects a JSON response with model information or an error if the model is not found.

```json
{
  "id": "jina-deepsearch-v1",
  "object": "model",
  "created": 1686935002,
  "owned_by": "jina-ai"
}
```

```json
{
  "error": {
    "message": "Model 'unknown-model' not found",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}
```

--------------------------------

### Run All Jest Tests

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Execute all unit and integration tests defined in the project using npm. This command is typically used to ensure code quality and correctness.

```bash
npm test
```

--------------------------------

### Configure Serper Search Provider

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Sets Serper (Google Search API) as the default search provider. Requires SERPER_API_KEY to be set.

```bash
export SERPER_API_KEY=...
```

```json
{
  "defaults": {
    "search_provider": "serper"
  }
}
```

--------------------------------

### Configure Brave Search Provider

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Sets Brave Search as the default search provider. Requires BRAVE_API_KEY to be set.

```bash
export BRAVE_API_KEY=...
```

```json
{
  "defaults": {
    "search_provider": "brave"
  }
}
```

--------------------------------

### chooseK()

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Selects the K most relevant items from a list of strings based on their embeddings and a given query.

```APIDOC
## chooseK()

### Description
Selects K most relevant items from array using embeddings.

### Signature
```typescript
export async function chooseK(
  items: string[],
  query: string,
  k: number,
  context: TrackerContext
): Promise<string[]>
```
```

--------------------------------

### Gemini Model Configuration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Configure the default model, temperature, and maximum tokens for Gemini. Recommended model is 'gemini-2.0-flash' for a balance of speed and intelligence.

```json
{
  "models": {
    "gemini": {
      "default": {
        "model": "gemini-2.0-flash",
        "temperature": 0.7,
        "maxTokens": 4000
      }
    }
  }
}
```

--------------------------------

### Sort and Select Top URLs

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Sorts URLs by their calculated score and returns the top N URLs. This is typically used after ranking URLs to get the most relevant ones.

```typescript
export function sortSelectURLs(
  urls: BoostedSearchSnippet[],
  maxURLs: number
): BoostedSearchSnippet[]
```

```typescript
const boosted = rankURLs(searchResults);
const topURLs = sortSelectURLs(boosted, 10);
// topURLs[0] has highest finalScore
```

--------------------------------

### Get Batch Text Embeddings

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Retrieves vector embeddings for a batch of text chunks. It supports batching API calls with a configurable chunkSize and uses a TrackerContext for token tracking.

```typescript
export async function getEmbeddings(
  texts: string[],
  context?: TrackerContext,
  chunkSize?: number
): Promise<number[][]>
```

```typescript
const embeddings = await getEmbeddings(
  ['machine learning', 'deep learning', 'cooking recipe'],
  context
);
// embeddings[0] and embeddings[1] will be similar
```

--------------------------------

### Run DeepResearch with a Query

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Execute the DeepResearch application with a specific query using npm. Ensure necessary API keys are exported as environment variables.

```bash
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 $QUERY
```

--------------------------------

### Express.js App with Routes

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Defines the default Express.js application export and lists the available API routes. This serves as the entry point for the OpenAI-compatible API server.

```typescript
// Express.js app with routes:
export default app;

// Routes:
app.get('/health')                          // Health check
app.get('/v1/models')                       // List models
app.get('/v1/models/:model')                // Get model
app.post('/v1/chat/completions')            // Main endpoint
```

--------------------------------

### cURL OpenAI Chat Completion Request

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Make a chat completion request to DeepResearch using cURL. This example shows how to send a non-streaming request with necessary headers and a JSON payload.

```bash
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": "latest Tesla news"}
    ],
    "stream": false
  }'
```

--------------------------------

### Reference and Citation Configuration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Configure the maximum number of returned URLs, annotations, and the minimum relevance score for citations. Use this to control the detail and relevance of extracted references.

```json
{
  "max_returned_urls": 10,
  "max_annotations": 10,
  "min_annotation_relevance": 0.7
}
```

--------------------------------

### Run Docker Container

Source: https://github.com/jina-ai/node-deepresearch/blob/main/README.md

Run the Jina AI Deep Research application as a Docker container, mapping the necessary port and setting required environment variables for API keys.

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

--------------------------------

### 400 Bad Request Response Example

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/08-errors-reference.md

This JSON response indicates a bad request due to invalid parameters or request body. It includes a general error message and specific details about the invalid parameter.

```json
{
  "error": "The \"messages\" parameter is required.",
  "details": [
    {
      "msg": "The \"messages\" parameter is required.",
      "param": "messages"
    }
  ]
}
```

--------------------------------

### /v1/chat/completions

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Main endpoint for chat completions, implementing OpenAI-compatible API.

```APIDOC
## POST /v1/chat/completions

### Description
Main endpoint for chat completions, implementing OpenAI-compatible API. See Endpoints reference for request/response schemas.

### Method
POST

### Endpoint
/v1/chat/completions

### Response
#### Success Response (200)
- (No specific fields documented)
```

--------------------------------

### Multi-Language Support for Research

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Research and respond in any language by specifying `language_code` for the response language and optionally `search_language_code` for the search query language. This example demonstrates Chinese, cross-lingual (English query, German search), and Spanish.

```typescript
// Chinese question, respond in Chinese
const chinese = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages: [
    { role: 'user', content: '什么是量子计算?' }
  ],
  language_code: 'zh'
});

// English question, search German sources, respond in English
const crossLingual = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages: [
    { role: 'user', content: 'German automotive industry trends' }
  ],
  language_code: 'en',
  search_language_code: 'de'  // Search in German
});

// Spanish research
const spanish = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages: [
    { role: 'user', content: 'últimas noticias de tecnología' }
  ],
  language_code: 'es'
});

```

--------------------------------

### Configure URL Filtering

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/07-configuration.md

Use `boost_hostnames`, `bad_hostnames`, and `only_hostnames` to influence search result ranking and filtering. `only_hostnames` overrides other hostname parameters.

```json
{
  "boost_hostnames": ["github.com", "arxiv.org"],
  "bad_hostnames": ["spam.com"],
  "only_hostnames": ["arxiv.org"]
}
```

--------------------------------

### TypeScript Configuration Types and Variables

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/10-module-index.md

Defines types for LLM providers and tool names, and declares configuration variables loaded from environment and config.json. Use these for setting up LLM clients and tool configurations.

```typescript
export type LLMProvider = 'openai' | 'gemini' | 'vertex';
export type ToolName = keyof typeof configJson.models.gemini.tools;

export const OPENAI_BASE_URL?: string;
export const GEMINI_API_KEY: string;
export const OPENAI_API_KEY: string;
export const JINA_API_KEY: string;
export const BRAVE_API_KEY?: string;
export const SERPER_API_KEY?: string;
export const SEARCH_PROVIDER: string;
export const STEP_SLEEP: number;
export const LLM_PROVIDER: LLMProvider;

export function getToolConfig(toolName: ToolName): ToolConfig;
export function getMaxTokens(toolName: ToolName): number;
export function getModel(toolName: ToolName): Model;
```

--------------------------------

### Prioritize or Restrict Domains with Hostnames

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/09-integration-guide.md

Use `only_hostnames` to restrict results to specific domains, `boost_hostnames` to prioritize certain domains, and `bad_hostnames` to exclude unwanted domains.

```typescript
const academic = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages: [{ role: 'user', content: 'latest quantum computing research' }],
  only_hostnames: ['arxiv.org', 'scholar.google.com']
});

const news = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages: [{ role: 'user', content: 'Trump election 2024' }],
  boost_hostnames: ['bbc.com', 'reuters.com', 'apnews.com'],
  bad_hostnames: ['facebook.com', 'twitter.com']
});

const nodealers = await client.chat.completions.create({
  model: 'jina-deepsearch-v1',
  messages: [{ role: 'user', content: 'how to choose a laptop' }],
  bad_hostnames: ['amazon.com', 'aliexpress.com', 'ebay.com']
});
```

--------------------------------

### processURLs() & addToAllURLs()

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Helper functions for URL collection and deduplication.

```APIDOC
## processURLs() & addToAllURLs()

### Description
These are helper functions used for collecting and deduplicating URLs.

### Method Signatures
```typescript
export function addToAllURLs(
  allURLs: Map<string, SearchSnippet>,
  newURLs: SearchSnippet[]
): void;

export function processURLs(
  urlMap: Record<string, SearchSnippet>
): SearchSnippet[];
```
```

--------------------------------

### buildMdFromAnswer()

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/06-api-reference-utilities.md

Builds markdown content from an answer action, applying footnote repair as part of the process.

```APIDOC
## buildMdFromAnswer()

### Description
Extracts markdown and applies footnote repair.

### Signature
```typescript
export function buildMdFromAnswer(answer: AnswerAction): string
```
```

--------------------------------

### API Keys and Endpoints Configuration

Source: https://github.com/jina-ai/node-deepresearch/blob/main/_autodocs/03-api-reference-agent.md

Lists available API keys and endpoints for various services. These are read from environment variables or config.json, with environment variables taking precedence.

```typescript
export const GEMINI_API_KEY: string;
export const OPENAI_API_KEY: string;
export const OPENAI_BASE_URL?: string;  // Custom endpoint (local LLM)
export const JINA_API_KEY: string;
export const BRAVE_API_KEY?: string;
export const SERPER_API_KEY?: string;
export const SEARCH_PROVIDER: string;
export const STEP_SLEEP: number;  // Delay between steps (seconds)
export const LLM_PROVIDER: LLMProvider;
```