### Local Development Setup using .env.local

Source: https://deepwiki.com/dzhng/deep-research/5-system-configuration

Provides an example of a `.env.local` file for local development setup. This file contains essential API keys and configuration settings such as FIRECHECK_KEY, OPENAI_KEY, and CONTEXT_SIZE. The code block shows the content of the environment file.

```dotenv
FIRECRAWL_KEY="your_firecrawl_key"
OPENAI_KEY="your_openai_key"
CONTEXT_SIZE="128000"

```

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

### LLM Provider Configuration Example (.env.example)

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Provides an example of how LLM providers are configured using environment variables. This snippet specifically shows settings for OpenAI and Fireworks API, including keys and model specifications.

```text
# .env.example

OPENAI_KEY="your_openai_key"
FIREWORKS_KEY="your_fireworks_key"
FIREWORKS_MODEL="deepseek-coder-v2-instruct"
CONTEXT_SIZE="128000"
```

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

### Starting the Application Locally

Source: https://deepwiki.com/dzhng/deep-research/5-system-configuration

Shows the command to start the Deep Research application locally after configuring the `.env.local` file. This command is executed in the project root directory.

```bash
npm start

```

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

### Debugging AI Provider Initialization - JavaScript

Source: https://deepwiki.com/dzhng/deep-research/3-ai-integration

This snippet demonstrates how to check if AI providers like OpenAI and Fireworks have been successfully initialized. It uses simple console logging to display the boolean status of each provider. This is useful for verifying the environment setup during debugging.

```javascript
// Check which providers are initialized
console.log('OpenAI:', !!openai);
console.log('Fireworks:', !!fireworks);
console.log('Custom Model:', !!customModel);
```

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

### Express.js API Server Initialization

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

Initializes the Deep Research API server using Express.js. It sets up middleware and starts listening for incoming requests on a configured port. This code is essential for running the API service.

```typescript
import express from "express";

const app = express();

app.use(express.json());

// ... other middleware and routes ...

const PORT = process.env.PORT || 3051;
app.listen(PORT, () => {
  console.log(`API server listening on port ${PORT}`);
});
```

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

### Initialize and Use RecursiveCharacterTextSplitter in TypeScript

Source: https://deepwiki.com/dzhng/deep-research/8-development-and-build-system

The RecursiveCharacterTextSplitter breaks down large text documents into smaller chunks suitable for AI models. It intelligently selects separators, splits text recursively, and maintains overlap for context preservation. This example shows initialization with custom chunk size and overlap, followed by splitting a long search result.

```typescript
import { RecursiveCharacterTextSplitter } from './text-splitter';

// Example initialization
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 4000,
  chunkOverlap: 200,
});

// Split a long text into manageable chunks
const chunks = splitter.splitText(longSearchResult);

// Process each chunk with an AI model
for (const chunk of chunks) {
  // Send to AI model for processing
}
```

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

### Basic Configuration Process

Source: https://deepwiki.com/dzhng/deep-research/5-system-configuration

Illustrates the fundamental steps for setting up Deep Research using environment variables. Key variables like FIRECHECK_KEY and OPENAI_KEY are essential for API connections. The code block is a placeholder and does not contain executable code.

```text

```

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

### Initialize Firecrawl API Client

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Demonstrates how to initialize the Firecrawl API client using an API key. It also shows how to specify a base URL for self-hosted Firecrawl instances, which is useful for custom deployments or testing environments.

```typescript
const firecrawl = new CrawlAgent({
  apiKey: process.env.FIRECRAWL_KEY,
  baseUrl: process.env.FIRECRAWL_BASE_URL,
});
```

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

### Configure LLM Providers (OpenAI)

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Details the environment variables required to configure the OpenAI API. This includes the API key and an optional setting for context window size, which can affect the amount of information the model can process at once.

```text
OPENAI_KEY="your_openai_key"
CONTEXT_SIZE="128000"                       # Optional context window size
```

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

### AI Integration Core Functions - TypeScript

Source: https://deepwiki.com/dzhng/deep-research/3-ai-integration

Provides `getModel()` to retrieve language model instances and `trimPrompt()` to optimize prompts for context window limitations. These functions are essential for interacting with AI models in the research pipeline. No external dependencies are explicitly mentioned for these core functions.

```typescript
/**
 * Returns configured LanguageModelV1 instance
 */
function getModel(): LanguageModelV1;

/**
 * Optimizes prompts for context window limits
 */
function trimPrompt(prompt: string): string;
```

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

### CLI Interface Orchestration (TypeScript)

Source: https://deepwiki.com/dzhng/deep-research/2

Orchestrates user interactions from initial query collection to final report generation using Node.js.

```typescript
import readline from 'readline';

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

async function main() {
  // ... main orchestration logic ...
  rl.close();
}

main();
```

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

### Configure Firecrawl Environment Variables

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Lists the environment variables used to configure the Firecrawl service. This includes the API key, an optional base URL for self-hosted instances, and a setting for concurrency limits.

```text
FIRECRAWL_KEY="your_firecrawl_key"
FIRECRAWL_BASE_URL="http://localhost:3002"  # Optional for self-hosted
FIRECRAWL_CONCURRENCY="2"                   # Optional, default is 2
```

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

### Core Input Function using Readline (TypeScript)

Source: https://deepwiki.com/dzhng/deep-research/2

Primary mechanism for synchronous user input collection via Node.js's readline interface.

```typescript
async function askQuestion(query: string): Promise<string> {
  return new Promise(resolve => {
    rl.question(query, resolve);
  });
}
```

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

### Console Logging Utility (TypeScript)

Source: https://deepwiki.com/dzhng/deep-research/2

A helper function for standardized console output, wrapping `console.log()` for consistent formatting.

```typescript
function log(message: string, level: 'info' | 'warn' | 'error' = 'info'): void {
  const timestamp = new Date().toISOString();
  console.log(`[${timestamp}] [${level.toUpperCase()}] ${message}`);
}

// Example usage:
// log('Research process started.');
// log('Encountered a potential issue.', 'warn');
```

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

### Resource Cleanup with Readline Interface (TypeScript)

Source: https://deepwiki.com/dzhng/deep-research/2

Ensures proper resource cleanup by closing the readline interface after all user interactions are complete.

```typescript
import readline from 'readline';

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

async function cleanup() {
  // ... perform all interactions ...
  rl.close();
  console.log('Interface closed. Exiting.');
}

cleanup();
```

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

### Configure Firecrawl Search Parameters

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Shows the configuration options for Firecrawl searches within the Deep Research process. This includes setting timeouts, limiting the number of results, and specifying the desired output format for scraped content, such as markdown.

```javascript
// Search parameters
timeout: 15000,       // 15-second timeout
limit: 5,             // Limit to 5 results
scrapeOptions: { formats: ['markdown'] }  // Request markdown format
```

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

### Generate Feedback Questions with AI in TypeScript

Source: https://deepwiki.com/dzhng/deep-research/8-development-and-build-system

The Feedback Generator utility creates clarifying follow-up questions based on a user's research query. It uses an AI model to generate potential questions and validates the output using Zod schemas. This function is typically called early in the research process to refine the user's input.

```typescript
import { z } from 'zod';
import { generateObject } from 'ai'; // Assuming 'ai' is the library for AI interactions
import { getModel } from './model'; // Assuming a function to get the AI model

async function generateFeedback({
  query,
  numQuestions = 3,
}: { query: string; numQuestions?: number }) {
  const systemPrompt = () => "You are a helpful assistant that generates research questions.";

  const userFeedback = await generateObject({
    model: getModel(),
    system: systemPrompt(),
    prompt: `Given the following query from the user, ask some follow up questions to clarify the research direction... ${query}`,
    schema: z.object({
      questions: z.array(z.string())
    }),
  });

  return userFeedback.object.questions.slice(0, numQuestions);
}
```

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

### Output Mode Selection Logic (TypeScript)

Source: https://deepwiki.com/dzhng/deep-research/2

Determines the output mode (report or answer) based on user input and calls the appropriate file writing function.

```typescript
async function selectOutputMode(researchData: any, query: string, followUps: any[]) {
  const { researchMode } = await collectParameters(); // Assuming collectParameters is defined elsewhere

  if (researchMode === 'report') {
    await writeFinalReport(researchData, query, followUps);
  } else {
    await writeFinalAnswer(researchData, query);
  }
}
```

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

### Configure Fireworks API Key

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Set the FIREWORKS_KEY environment variable to authenticate with the Fireworks API for DeepSeek R1. This is essential for using Fireworks as your LLM provider.

```bash
FIREWORKS_KEY="your_fireworks_key"

```

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

### Configure Custom LLM Provider Endpoint and Model

Source: https://deepwiki.com/dzhng/deep-research/4-external-services

Configure custom endpoints and model names for LLM providers. This allows integration with local or self-hosted LLM services, specifying the API endpoint and the desired model.

```bash
OPENAI_ENDPOINT="http://localhost:11434/v1" # Custom endpoint
CUSTOM_MODEL="llama3.1"                     # Custom model name

```

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

### Interactive Parameter Collection Logic (TypeScript)

Source: https://deepwiki.com/dzhng/deep-research/2

Implements a multi-stage parameter collection process with conditional logic based on user preferences, handling input validation and defaults.

```typescript
async function collectParameters() {
  const breadthStr = await askQuestion('Enter research breadth (recommended 2-10, default 4): ');
  let breadth = parseInt(breadthStr) || 4;
  if (breadth < 2) breadth = 2;
  if (breadth > 10) breadth = 10;

  const depthStr = await askQuestion('Enter research depth (recommended 1-5, default 2): ');
  let depth = parseInt(depthStr) || 2;
  if (depth < 1) depth = 1;
  if (depth > 5) depth = 5;

  const mode = await askQuestion('Do you want to generate a long report or a specific answer? (report/answer, default report): ');
  const researchMode = mode.toLowerCase() === 'answer' ? 'answer' : 'report';

  return { breadth, depth, researchMode };
}
```

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

### Report Generation Endpoint

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

The /api/generate-report endpoint performs the same research process but generates a comprehensive report instead of a concise answer. It accepts a query, optional depth, and optional breadth parameters.

```APIDOC
## POST /api/generate-report

### Description
Performs deep research on a given query and generates a comprehensive report, along with supporting data.

### Method
POST

### Endpoint
/api/generate-report

### Parameters
#### Query Parameters

#### Request Body
- **query** (string) - Required - The research question or topic for report generation
- **depth** (number) - Optional - Number of research iterations (1-5). Default: 3
- **breadth** (number) - Optional - Number of search queries per iteration (3-10). Default: 3

### Response
#### Success Response (200)
- **success** (boolean) - Always `true` for successful requests
- **report** (string) - Generated comprehensive report content
- **learnings** (string[]) - Array of key insights discovered during research
- **visitedUrls** (string[]) - List of URLs that were scraped during research

#### Response Example
```json
{
  "success": true,
  "report": "Generated comprehensive report content...",
  "learnings": [
    "Key insight 1",
    "Key insight 2"
  ],
  "visitedUrls": [
    "https://example.com/report-source1",
    "https://example.com/report-source2"
  ]
}
```

#### Error Handling
- **Client Error (400):**
```json
{
  "error": "Query is required"
}
```
- **Server Error (500):**
```json
{
  "error": "An error occurred during research",
  "message": "Detailed error message"
}
```
```

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

### Deep Research Endpoint - POST /api/research

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

The POST /api/research endpoint initiates a deep research operation. It accepts a query, depth, and breadth for the research process and returns a synthesized answer, key learnings, and visited URLs. Handles both successful and error responses.

```typescript
import express, { Request, Response } from "express";

const router = express.Router();

// Assume researchFunction is imported and handles the actual research logic
// import { researchFunction } from "./research";

router.post("/research", async (req: Request, res: Response) => {
  const { query, depth = 3, breadth = 3 } = req.body;

  if (!query) {
    return res.status(400).json({ error: "Query is required" });
  }

  try {
    // const result = await researchFunction(query, depth, breadth);
    // Placeholder for actual research result
    const result = {
      success: true,
      answer: `Synthesized answer for: ${query}`,
      learnings: [`Learning 1 about ${query}`, `Learning 2 about ${query}`],
      visitedUrls: ["http://example.com/source1", "http://example.com/source2"]
    };
    res.status(200).json(result);
  } catch (error: any) {
    console.error("Research error:", error);
    res.status(500).json({
      error: "An error occurred during research",
      message: error.message
    });
  }
});

export default router;
```

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

### Report Generation API

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

This endpoint generates comprehensive research reports using the core research engine.

```APIDOC
## POST /api/generate-report

### Description
Generates comprehensive research reports by integrating `deepResearch()` and `writeFinalReport()` core functions.

### Method
POST

### Endpoint
/api/generate-report

### Parameters
This endpoint does not have explicit path or query parameters documented.

#### Request Body
* **query** (string) - Required - The research question or topic for the report.
* **depth** (string) - Optional - The desired depth of the report (e.g., 'detailed', 'summary').

### Request Example
```json
{
  "query": "The impact of climate change on global economies",
  "depth": "detailed"
}
```

### Response
#### Success Response (200)
- **report** (string) - The comprehensive research report.

#### Response Example
```json
{
  "report": "Climate change poses significant risks to global economies through impacts on agriculture, infrastructure, and human health. This detailed report explores the multifaceted economic consequences, including supply chain disruptions, increased insurance costs, and the transition to renewable energy sources..."
}
```
```

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

### Report Generation Endpoint - POST /api/generate-report

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

The POST /api/generate-report endpoint triggers a research process to generate a comprehensive report. It accepts a query, depth, and breadth. The endpoint is intended to return a JSON object with the report, learnings, and visited URLs, but currently has a bug returning the report object directly.

```typescript
import express, { Request, Response } from "express";

const router = express.Router();

// Assume writeFinalReport is imported and handles report generation
// import { writeFinalReport } from "./reportGenerator";

router.post("/generate-report", async (req: Request, res: Response) => {
  const { query, depth = 3, breadth = 3 } = req.body;

  if (!query) {
    return res.status(400).json({ error: "Query is required" });
  }

  try {
    // Placeholder for actual report generation logic
    // const reportData = await writeFinalReport(query, depth, breadth);
    const reportData = {
      success: true,
      report: `Comprehensive report content for: ${query}`,
      learnings: [`Report Learning 1`, `Report Learning 2`],
      visitedUrls: ["http://example.com/report_source1"]
    };

    // NOTE: Current implementation has a bug returning reportData directly.
    // Expected behavior is to return JSON response like:
    // res.status(200).json({
    //   success: true,
    //   report: reportData.report,
    //   learnings: reportData.learnings,
    //   visitedUrls: reportData.visitedUrls
    // });

    // Simulating the bug for demonstration:
    // res.send(reportData.report); // This would be the buggy behavior

    // Corrected behavior (as intended):
    res.status(200).json({
      success: true,
      report: reportData.report,
      learnings: reportData.learnings,
      visitedUrls: reportData.visitedUrls
    });

  } catch (error: any) {
    console.error("Report generation error:", error);
    res.status(500).json({
      error: "An error occurred during research",
      message: error.message
    });
  }
});

export default router;
```

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

### Research Endpoint API

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

This endpoint is used to generate concise research answers by leveraging the core research engine.

```APIDOC
## POST /api/research

### Description
Generates concise research answers using the `deepResearch()` and `writeFinalAnswer()` core functions.

### Method
POST

### Endpoint
/api/research

### Parameters
This endpoint does not have explicit path or query parameters documented.

#### Request Body
* **query** (string) - Required - The research question or topic.
* **max_tokens** (integer) - Optional - The maximum number of tokens for the answer.

### Request Example
```json
{
  "query": "What are the latest advancements in AI?",
  "max_tokens": 150
}
```

### Response
#### Success Response (200)
- **answer** (string) - The concise research answer.

#### Response Example
```json
{
  "answer": "Recent advancements in AI include breakthroughs in large language models, generative adversarial networks, and reinforcement learning, leading to more sophisticated applications in natural language processing and computer vision."
}
```
```

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

### Research Endpoint

Source: https://deepwiki.com/dzhng/deep-research/7-api-reference

The /api/research endpoint performs deep research on a given query and returns a synthesized answer along with supporting data. It accepts a query, optional depth, and optional breadth parameters.

```APIDOC
## POST /api/research

### Description
Performs deep research on a given query and returns a synthesized answer along with supporting data.

### Method
POST

### Endpoint
/api/research

### Parameters
#### Query Parameters

#### Request Body
- **query** (string) - Required - The research question or topic to investigate
- **depth** (number) - Optional - Number of research iterations (1-5). Default: 3
- **breadth** (number) - Optional - Number of search queries per iteration (3-10). Default: 3

### Request Example
```json
{
  "query": "What are the latest developments in quantum computing?",
  "depth": 2,
  "breadth": 4
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Always `true` for successful requests
- **answer** (string) - Synthesized answer to the research query
- **learnings** (string[]) - Array of key insights discovered during research
- **visitedUrls** (string[]) - List of URLs that were scraped during research

#### Response Example
```json
{
  "success": true,
  "answer": "Recent developments in quantum computing include...",
  "learnings": [
    "IBM announced a new 1000-qubit processor...",
    "Google achieved quantum supremacy in specific calculations..."
  ],
  "visitedUrls": [
    "https://example.com/quantum-news",
    "https://research.ibm.com/quantum"
  ]
}
```

#### Error Handling
- **Client Error (400):**
```json
{
  "error": "Query is required"
}
```
- **Server Error (500):**
```json
{
  "error": "An error occurred during research",
  "message": "Detailed error message"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.