Answer API

import { Valyu } from "valyu-js";

const valyu = new Valyu();

// Non-streaming (default) - waits for complete response
const response = await valyu.answer(
  "What are the latest developments in quantum computing?"
);

if (response.success) {
  console.log("Answer:", response.contents);
  console.log("Sources used:", response.search_metadata.number_of_results);
}

import { Valyu, AnswerStreamChunk } from "valyu-js";

const valyu = new Valyu();

// Streaming mode - returns async generator yielding chunks
const stream = await valyu.answer("What is machine learning?", { streaming: true });

for await (const chunk of stream as AsyncGenerator<AnswerStreamChunk>) {
  if (chunk.type === "search_results") {
    console.log(`Found ${chunk.search_results?.length} sources`);
  } else if (chunk.type === "content") {
    // Print content as it streams in
    if (chunk.content) {
      process.stdout.write(chunk.content);
    }
  } else if (chunk.type === "metadata") {
    console.log(`\nCost: $${chunk.cost?.total_deduction_dollars.toFixed(4)}`);
    console.log(`Tokens: ${chunk.ai_usage?.input_tokens} in, ${chunk.ai_usage?.output_tokens} out`);
  } else if (chunk.type === "done") {
    console.log("\n[Complete]");
  } else if (chunk.type === "error") {
    console.error(`Error: ${chunk.error}`);
  }
}

type AnswerResponse = AnswerSuccessResponse | AnswerErrorResponse;

interface AnswerSuccessResponse {
  success: true;
  tx_id: string;
  original_query: string;
  contents: string | Record<string, any>; // string or structured object
  data_type: "unstructured" | "structured";
  search_results: SearchResult[];
  search_metadata: SearchMetadata;
  ai_usage: AIUsage;
  cost: Cost;
}

interface AnswerErrorResponse {
  success: false;
  error: string;
}

const response = await valyu.answer(
  "How do neural networks learn?"
);

if (response.success) {
  console.log(response.contents);
}

const response = await valyu.answer(
  "Explain quantum computing",
  {
    systemInstructions: "You are a computer science professor. Explain concepts clearly with practical examples and avoid overly technical jargon.",
  }
);

const response = await valyu.answer(
  "What is the impact of AI on software development?",
  {
    structuredOutput: {
      type: "object",
      properties: {
        summary: {
          type: "string",
          description: "Brief summary of AI's impact"
        },
        key_impacts: {
          type: "array",
          items: { type: "string" },
          description: "List of key impacts"
        },
        benefits: {
          type: "array",
          items: { type: "string" },
          maxItems: 5
        },
        challenges: {
          type: "array", 
          items: { type: "string" },
          maxItems: 5
        },
        future_outlook: {
          type: "string",
          description: "Future implications and trends"
        }
      },
      required: ["summary", "key_impacts", "future_outlook"]
    }
  }
);

if (response.success && response.data_type === "structured") {
  const structuredAnswer = response.contents as any;
  console.log("Summary:", structuredAnswer.summary);
  console.log("Key impacts:", structuredAnswer.key_impacts);
}

const response = await valyu.answer(
  "What are the best practices for React performance optimization?",
  {
    searchType: "web",
    includedSources: [
      "react.dev", 
      "developer.mozilla.org",
      "web.dev"
    ],
    systemInstructions: "Focus on official recommendations and proven techniques"
  }
);

const response = await valyu.answer(
  "What are the current renewable energy policies and incentives?",
  {
    countryCode: "US",
    startDate: "2024-01-01",
    systemInstructions: "Focus on federal and state-level policies with specific program details"
  }
);

const response = await valyu.answer(
  "What are the latest breakthroughs in AI model architectures?",
  {
    startDate: "2024-06-01",
    endDate: "2024-12-01",
    searchType: "proprietary",
    includedSources: ["valyu/valyu-arxiv"],
    systemInstructions: "Focus on novel architectures and their performance improvements"
  }
);

const response = await valyu.answer(
  "What's the current status of the stock market?",
  {
    fastMode: true,
  }
);

const response = await valyu.answer(
  "How has Tesla's stock performance compared to other EV companies in 2024?",
  {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-stocks"],
    structuredOutput: {
      type: "object",
      properties: {
        tesla_performance: {
          type: "object",
          properties: {
            ytd_return: { type: "string" },
            current_price: { type: "string" },
            key_events: { 
              type: "array", 
              items: { type: "string" } 
            }
          }
        },
        competitor_comparison: {
          type: "array",
          items: {
            type: "object",
            properties: {
              company: { type: "string" },
              ytd_return: { type: "string" },
              relative_performance: { type: "string" }
            }
          }
        },
        market_analysis: { type: "string" }
      }
    },
    systemInstructions: "Provide detailed financial analysis with specific metrics, key events, and market context. Include percentage changes and dollar values where applicable."
  }
);

if (response.success && response.data_type === "structured") {
  const analysis = response.contents as any;
  
  // Display Tesla performance
  console.log("Tesla Performance:");
  console.log(`YTD Return: ${analysis.tesla_performance.ytd_return}`);
  console.log(`Current Price: ${analysis.tesla_performance.current_price}`);
  
  // Compare with competitors
  console.log("\nCompetitor Analysis:");
  analysis.competitor_comparison.forEach((comp: any) => {
    console.log(`${comp.company}: ${comp.ytd_return} (${comp.relative_performance})`);
  });
  
  console.log(`\nMarket Analysis: ${analysis.market_analysis}`);
}

async function getTechnicalGuide(topic: string) {
  const response = await valyu.answer(
    `How do I implement ${topic} in a Node.js application?`,
    {
      systemInstructions: "Provide step-by-step implementation guidance with code examples, security best practices, and common pitfalls to avoid. Structure the response as a comprehensive tutorial.",
      includedSources: [
        "nodejs.org",
        "developer.mozilla.org",
        "github.com"
      ],
      structuredOutput: {
        type: "object",
        properties: {
          overview: {
            type: "string",
            description: "Brief overview of the implementation"
          },
          prerequisites: {
            type: "array",
            items: { type: "string" },
            description: "Required dependencies and setup"
          },
          implementation_steps: {
            type: "array",
            items: {
              type: "object",
              properties: {
                step: { type: "string" },
                description: { type: "string" },
                code_example: { type: "string" }
              }
            }
          },
          security_considerations: {
            type: "array",
            items: { type: "string" }
          },
          common_pitfalls: {
            type: "array",
            items: { type: "string" }
          },
          additional_resources: {
            type: "array",
            items: { type: "string" }
          }
        },
        required: ["overview", "implementation_steps", "security_considerations"]
      }
    }
  );

  if (response.success && response.data_type === "structured") {
    const guide = response.contents as any;
    
    console.log("=== Technical Implementation Guide ===");
    console.log(`\nOverview: ${guide.overview}`);
    
    console.log("\nPrerequisites:");
    guide.prerequisites?.forEach((req: string, i: number) => {
      console.log(`${i + 1}. ${req}`);
    });
    
    console.log("\nImplementation Steps:");
    guide.implementation_steps.forEach((step: any, i: number) => {
      console.log(`\n${i + 1}. ${step.step}`);
      console.log(`   ${step.description}`);
      if (step.code_example) {
        console.log(`   Code: ${step.code_example}`);
      }
    });
    
    return guide;
  }
  
  return null;
}

// Usage example
const oauthGuide = await getTechnicalGuide("OAuth 2.0 authentication");

async function compareOptions(topic: string, options: string[]) {
  const response = await valyu.answer(
    `Compare the pros and cons of ${options.join(", ")} for ${topic}`,
    {
      systemInstructions: "Provide a comprehensive comparison with objective analysis. Include specific examples, metrics, and real-world considerations for each option.",
      structuredOutput: {
        type: "object",
        properties: {
          comparison_summary: {
            type: "string",
            description: "Brief overview of the comparison"
          },
          options: {
            type: "array",
            items: {
              type: "object", 
              properties: {
                name: { type: "string" },
                pros: { 
                  type: "array", 
                  items: { type: "string" } 
                },
                cons: { 
                  type: "array", 
                  items: { type: "string" } 
                },
                best_for: { type: "string" },
                learning_curve: { type: "string" },
                market_adoption: { type: "string" },
                performance_rating: { type: "string" }
              }
            }
          },
          decision_matrix: {
            type: "object",
            properties: {
              criteria: {
                type: "array",
                items: { type: "string" }
              },
              scores: {
                type: "object",
                description: "Scores for each option on each criteria"
              }
            }
          },
          recommendation: { 
            type: "string",
            description: "Final recommendation with reasoning"
          }
        },
        required: ["comparison_summary", "options", "recommendation"]
      }
    }
  );

  if (response.success && response.data_type === "structured") {
    const comparison = response.contents as any;
    
    console.log("=== Comparative Analysis ===");
    console.log(`\n${comparison.comparison_summary}`);
    
    console.log("\n=== Option Analysis ===");
    comparison.options.forEach((option: any) => {
      console.log(`\n${option.name.toUpperCase()}`);
      console.log(`Best for: ${option.best_for}`);
      console.log(`Learning curve: ${option.learning_curve}`);
      console.log(`Market adoption: ${option.market_adoption}`);
      
      console.log("Pros:");
      option.pros.forEach((pro: string) => console.log(`  ✓ ${pro}`));
      
      console.log("Cons:");
      option.cons.forEach((con: string) => console.log(`  ✗ ${con}`));
    });
    
    console.log(`\n=== Final Recommendation ===`);
    console.log(comparison.recommendation);
    
    return comparison;
  }
  
  return null;
}

// Usage examples
const frameworkComparison = await compareOptions(
  "enterprise web applications", 
  ["React", "Vue", "Angular"]
);

const databaseComparison = await compareOptions(
  "scalable microservices architecture",
  ["PostgreSQL", "MongoDB", "Cassandra"]
);

const response = await valyu.answer(query, options);

if (!response.success) {
  console.error("Answer generation failed:", response.error);
  
  // Handle specific error cases
  if (response.error.includes("insufficient credits")) {
    console.log("Please add more credits to your account");
  } else if (response.error.includes("invalid")) {
    console.log("Check your query and options");
  }
  
  return;
}

// Process successful response
console.log(`Transaction ID: ${response.tx_id}`);
console.log(`Data type: ${response.data_type}`);
console.log(`Sources processed: ${response.search_metadata.number_of_results}`);
console.log(`Answer: ${response.contents}`);

const response = await valyu.answer(query, {
  systemInstructions: "Provide detailed, evidence-based answers with specific examples",
  searchType: "proprietary", // Use high-quality academic/professional sources
  includedSources: ["authoritative-domain.com"],
  startDate: "2024-01-01" // Focus on recent information
});

const response = await valyu.answer(query, {
  structuredOutput: schema
});

if (response.success) {
  if (response.data_type === "structured") {
    const structuredData = response.contents as Record<string, any>;
    // Process structured data
  } else {
    const textAnswer = response.contents as string;
    // Process text answer
  }
}