DeepResearch API

import { Valyu } from "valyu-js";

const valyu = new Valyu();

// Create a research task
const task = await valyu.deepresearch.create({
  query: "What are the key differences between RAG and fine-tuning for LLMs?",
  mode: "standard"
});

if (task.success) {
  console.log(`Task created: ${task.deepresearch_id}`);
  
  // Wait for completion with progress updates
  const result = await valyu.deepresearch.wait(task.deepresearch_id, {
    onProgress: (s) => console.log(`Status: ${s.status}`)
  });
  
  if (result.status === "completed") {
    console.log(result.output);
    console.log(`Cost: $${result.cost}`);
  }
}

// Use fast mode for quick lookups
const task = await valyu.deepresearch.create({
  query: "What is quantum computing?",
  mode: "fast"
});

// Use heavy mode for complex research
const task = await valyu.deepresearch.create({
  query: "Analyze the competitive landscape of cloud computing in 2024",
  mode: "heavy"
});

const task = await valyu.deepresearch.create({
  query: "Explain quantum computing advancements in 2024",
  outputFormats: ["markdown"]
});

const task = await valyu.deepresearch.create({
  query: "Write a report on renewable energy trends",
  outputFormats: ["markdown", "pdf"]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id!);

if (result.pdf_url) {
  console.log(`PDF available at: ${result.pdf_url}`);
}

const task = await valyu.deepresearch.create({
  query: "Research competitor pricing in the SaaS market",
  outputFormats: [{
    type: "object",
    properties: {
      competitors: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            pricing_model: { type: "string" },
            price_range: { type: "string" },
            key_features: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["name", "pricing_model"]
        }
      },
      market_summary: { type: "string" },
      recommendations: {
        type: "array",
        items: { type: "string" }
      }
    },
    required: ["competitors", "market_summary"]
  }]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id!);

if (result.output_type === "json") {
  const data = result.output as any;
  data.competitors.forEach((competitor: any) => {
    console.log(`${competitor.name}: ${competitor.pricing_model}`);
  });
}

const task = await valyu.deepresearch.create({
  query: "Research competitor pricing in the SaaS market",
  outputFormats: [{
    type: "object",
    properties: {
      competitors: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            pricing_model: { type: "string" }
          }
        }
      }
    },
    required: ["competitors"]
  }]
});

const task = await valyu.deepresearch.create({
  query: "Research AI trends",
  search: {
    searchType: "proprietary",
    includedSources: ["academic", "finance"],
    startDate: "2024-01-01",
    endDate: "2024-12-31",
    countryCode: "US"  // Filter web results by country
  }
});

import * as fs from "fs";

// Read and encode a PDF
const pdfBuffer = fs.readFileSync("report.pdf");
const pdfData = pdfBuffer.toString("base64");

const task = await valyu.deepresearch.create({
  query: "Summarize the key findings and compare with market trends",
  model: "heavy",
  files: [{
    data: `data:application/pdf;base64,${pdfData}`,
    filename: "report.pdf",
    mediaType: "application/pdf",
    context: "Q4 2024 financial report"  // Optional context
  }]
});

const task = await valyu.deepresearch.create({
  query: "Research the top 20 AI companies in 2024",
  deliverables: [
    "CSV file with company names, founding year, and funding",
    "PowerPoint presentation with 5 slides summarizing key findings"
  ]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id);

if (result.deliverables) {
  for (const deliverable of result.deliverables) {
    if (deliverable.status === "completed") {
      console.log(`✅ ${deliverable.title}`);
      console.log(`   Download: ${deliverable.url}`);
      if (deliverable.row_count) {
        console.log(`   Rows: ${deliverable.row_count}`);
      }
    }
  }
}

const task = await valyu.deepresearch.create({
  query: "Analyze startup funding trends in 2024",
  deliverables: [
    {
      type: "xlsx",
      description: "Startup funding data with company details",
      columns: ["Company", "Funding Amount", "Date", "Investors", "Stage"],
      includeHeaders: true,
      sheetName: "Funding Data"
    },
    {
      type: "pptx",
      description: "Executive summary presentation",
      slides: 10,
      template: "modern"
    },
    {
      type: "pdf",
      description: "Detailed analysis report with charts and insights"
    }
  ]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id);

// Access deliverables
for (const deliverable of result.deliverables) {
  console.log(`${deliverable.type.toUpperCase()}: ${deliverable.title}`);
  console.log(`Status: ${deliverable.status}`);
  if (deliverable.status === "completed") {
    console.log(`Download: ${deliverable.url}`);
  } else if (deliverable.status === "failed") {
    console.log(`Error: ${deliverable.error}`);
  }
}

interface DeliverableResult {
  id: string;
  request: string;  // Original description
  type: "csv" | "xlsx" | "pptx" | "docx" | "pdf" | "unknown";
  status: "completed" | "failed";
  title: string;  // Generated filename
  url: string;  // Download URL (token-signed, expires)
  s3_key: string;
  row_count?: number;  // For CSV/Excel
  column_count?: number;  // For CSV/Excel
  error?: string;  // If failed
  created_at: string;  // ISO 8601 timestamp string
}

const task = await valyu.deepresearch.create({
  query: "Compare the approaches described in these articles",
  urls: [
    "https://example.com/article-1",
    "https://example.com/article-2"
  ]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id!);

if (result.status === "completed") {
  console.log(result.output);
}

const result = await valyu.deepresearch.wait(task.deepresearch_id!, {
  pollInterval: 5000,      // Check every 5 seconds
  maxWaitTime: 900000,     // Timeout after 15 minutes (standard mode)
  onProgress: (status) => {
    if (status.progress) {
      const pct = (status.progress.current_step / status.progress.total_steps) * 100;
      console.log(`Progress: ${pct.toFixed(0)}% - Step ${status.progress.current_step}/${status.progress.total_steps}`);
    }
    console.log(`Status: ${status.status}`);
  }
});

interface DeepResearchStatusResponse {
  success: boolean;
  deepresearch_id?: string;
  status?: "queued" | "running" | "completed" | "failed" | "cancelled";
  query?: string;
  mode?: "fast" | "standard" | "heavy";
  output_type?: "markdown" | "json" | "toon";
  output?: string | Record<string, any>;  // Research output
  sources?: DeepResearchSource[];  // Sources used
  cost?: number;  // Fixed cost for the task
  created_at?: string;  // ISO 8601 timestamp string
  completed_at?: string;  // ISO 8601 timestamp string
  pdf_url?: string;  // PDF download URL
  images?: ImageMetadata[];  // Generated images
  deliverables?: DeliverableResult[];  // Generated deliverable files
  batch_id?: string;  // Batch ID if task belongs to a batch
  batch_task_id?: string;  // Batch task identifier if task belongs to a batch
  error?: string;  // Error message if failed
}

interface DeepResearchSource {
  title: string;
  url: string;
  snippet?: string;
  source?: string;  // web, pubmed, arxiv, etc.
  word_count?: number;
  doi?: string;  // For academic papers
}

const status = await valyu.deepresearch.status(taskId);

console.log(`Status: ${status.status}`);
if (status.progress) {
  console.log(`Step ${status.progress.current_step}/${status.progress.total_steps}`);
}

// Using API key (default)
const asset = await valyu.deepresearch.getAssets(taskId, assetId);

if (asset.success && asset.data) {
  // asset.data is a Buffer containing the binary data
  // asset.contentType contains the MIME type (e.g., "image/png", "application/pdf")
  fs.writeFileSync("output.png", asset.data);
}

// Using token
const asset = await valyu.deepresearch.getAssets(taskId, assetId, {
  token: "asset-access-token"
});

interface DeepResearchGetAssetsResponse {
  success: boolean;
  data?: Buffer;  // Binary asset data
  contentType?: string;  // MIME type (e.g., "image/png", "application/pdf")
  error?: string;
}

// Add first instruction
const response = await valyu.deepresearch.update(
  taskId,
  "Focus more on peer-reviewed sources from 2024"
);

if (response.success) {
  console.log("Instruction added");
}

// Add another instruction
await valyu.deepresearch.update(
  taskId,
  "Include a comparison table of major providers"
);

const response = await valyu.deepresearch.cancel(taskId);

if (response.success) {
  console.log("Task cancelled");
}

const response = await valyu.deepresearch.delete(taskId);

if (response.success) {
  console.log("Task deleted");
}

const tasks = await valyu.deepresearch.list({
  apiKeyId: "your-api-key-id",
  limit: 50
});

tasks.data?.forEach(task => {
  console.log(`${task.query?.substring(0, 50)}... - ${task.status}`);
});

const task = await valyu.deepresearch.create({
  query: "Research market trends in AI",
  webhookUrl: "https://your-app.com/webhooks/deepresearch"
});

// IMPORTANT: Save the secret immediately - it's only returned once
const webhookSecret = task.webhook_secret;

const task = await valyu.deepresearch.create({
  query: "Research query"
});

if (!task.success) {
  console.error(`Failed to create task: ${task.error}`);
  return;
}

try {
  const result = await valyu.deepresearch.wait(task.deepresearch_id!, {
    maxWaitTime: 1800000  // 30 minutes for standard, use 7200000 for heavy
  });
  
  if (result.status === "completed") {
    console.log(result.output);
  } else if (result.status === "failed") {
    console.error(`Research failed: ${result.error}`);
  }
  
} catch (error: any) {
  if (error.message.includes("Maximum wait time")) {
    console.log("Task timed out - cancelling");
    await valyu.deepresearch.cancel(task.deepresearch_id!);
  } else {
    console.error(`Task error: ${error.message}`);
  }
}

// Production: use webhooks instead of polling
const task = await valyu.deepresearch.create({
  query: "Research query",
  webhookUrl: "https://your-app.com/webhooks"
});

interface ResearchOutput {
  summary: string;
  key_findings: string[];
  recommendations: string[];
}

const result = await valyu.deepresearch.wait(taskId);

if (result.output_type === "json" && result.output) {
  const data = result.output as ResearchOutput;
  console.log(data.summary);
  data.key_findings.forEach(finding => console.log(`- ${finding}`));
}