Universal Deep Research (UDR)

The Universal Deep Research Backend (UDR-B) can be installed using an automated setup script or manually.

Automated Setup (Recommended)

1. Clone the repository and enter the backend directory.
2. Run python3 setup.py. This script handles directory creation (logs/, instances/, mock_instances/), environment configuration, and dependency installation.
3. Create API key files: tavily_api.txt and either nvdev_api.txt or openai_api.txt containing your keys.
4. Start the server using ./launch_server.sh.

Manual Setup

1. Clone the repository and enter the backend directory.
2. Create and activate a Python virtual environment.
3. Install dependencies via pip install -r requirements.txt.
4. Create directories: mkdir -p logs instances mock_instances.
5. Copy env.example to .env and configure it.
6. Create API key files (tavily_api.txt, nvdev_api.txt, or openai_api.txt).
7. Start the server using ./launch_server.sh.

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

# Automated Setup
git clone <repository-url>
cd backend
python3 setup.py

# Configure API keys
echo "your-tavily-api-key" > tavily_api.txt
echo "your-llm-api-key" > nvdev_api.txt

# Start server
./launch_server.sh

The frontend is configured using environment variables prefixed with NEXT_PUBLIC_. You should create a .env.local file for local development.

Backend API Configuration

• NEXT_PUBLIC_BACKEND_BASE_URL: The base URL of your backend server (default: http://localhost).
• NEXT_PUBLIC_BACKEND_PORT: The port your backend server is running on (default: 8000).
• NEXT_PUBLIC_API_VERSION: API version to use - v1 or v2 (default: v2).

Runtime Configuration

• NEXT_PUBLIC_DRY_RUN: Enable dry run mode - true or false (default: false). Use true during development to avoid actual API calls.
• NEXT_PUBLIC_ENABLE_V2_API: Enable V2 API - true or false (default: true).

Frontend Configuration

• NEXT_PUBLIC_FRONTEND_PORT: The port for the frontend development server (default: 3000).
• NEXT_PUBLIC_FRONTEND_HOST: The host for the frontend development server (default: localhost).

# Example for local development with dry run enabled
NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost
NEXT_PUBLIC_BACKEND_PORT=8000
NEXT_PUBLIC_API_VERSION=v2
NEXT_PUBLIC_DRY_RUN=true
NEXT_PUBLIC_ENABLE_V2_API=true

The ApplicationState type defines the possible states of the Universal Deep Research frontend. It is a discriminated union where the type field determines the current phase of the research process. This state tracks session metadata, timing, and research progress via ResearchEvent objects.

Possible states include:

• idle: The initial state before research begins.
• researching: The active phase where searches and queries are being performed.
• finalizing: The phase where research results are being processed or synthesized.
• stopped: The state when a research session has been manually or prematurely halted.
• error: An error state containing an error string describing the failure.
• done: The completed state after successful research and finalization.

Common fields across most states include:

• sessionKey: A unique identifier for the current research session.
• researchStartTimestamp / researchEndTimestamp: Timestamps for the research phase.
• searchCount / queryCount: Counters for the number of searches and queries performed.
• finalizationStartTimestamp / finalizationEndTimestamp: Timestamps for the finalization phase.
• events: An array of ResearchEvent objects tracking progress.

// Example of an error state structure
const state: ApplicationState = {
  type: 'error',
  error: 'Connection timed out',
  sessionKey: 'abc-123',
  researchStartTimestamp: 1715000000000,
  researchEndTimestamp: 0,
  searchCount: 5,
  queryCount: 3,
  finalizationStartTimestamp: 0,
  finalizationEndTimestamp: 0,
  events: []
};

Configure the backend behavior by editing the .env file in the backend directory. Key configuration groups include:

• Server: HOST, PORT, LOG_LEVEL.
• CORS: FRONTEND_URL (set this to your frontend's URL, e.g., http://localhost:3000).
• Model: DEFAULT_MODEL, LLM_BASE_URL, LLM_API_KEY_FILE.
• Search: TAVILY_API_KEY_FILE.
• Research: MAX_TOPICS, MAX_SEARCH_PHRASES, MOCK_DIRECTORY.
• Logging: LOG_DIR, TRACE_ENABLED.

# Server Configuration
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=info

# CORS Configuration
FRONTEND_URL=http://localhost:3000

# Model Configuration
DEFAULT_MODEL=llama-3.1-nemotron-253b
LLM_BASE_URL=https://integrate.api.nvidia.com/v1
LLM_API_KEY_FILE=nvdev_api.txt

# Search Configuration
TAVILY_API_KEY_FILE=tavily_api.txt

# Research Configuration
MAX_TOPICS=1
MAX_SEARCH_PHRASES=1
MOCK_DIRECTORY=mock_instances/stocks_24th_3_sections

# Logging Configuration
LOG_DIR=logs
TRACE_ENABLED=true