valyu-best-practices

name valyu-best-practices description Complete Valyu API toolkit for AI agents. Use this skill when asked to perform real-time search across web, academic, medical, transportation, financial sources, content extraction from URLs, AI-powered answers with citations, or comprehensive deep research reports. license MIT compatibility Requires network access and valid Valyu API key metadata {"author":"valyu","version":"1.0"} Valyu Best Practices This skill provides instructions for using the Valyu API to perform search, content extraction, AI-powered answers, and deep research tasks. Quick Reference: Choosing the Right API Use this decision tree to select the appropriate Valyu API: What do you need? ├─ Find information across multiple sources │ └─ Use Search API │ ├─ Extract content from specific URLs │ └─ Use Contents API │ ├─ Get an AI-synthesized answer with citations │ └─ Use Answer API │ ├─ Generate a comprehensive research report │ └─ Use DeepResearch API │ └─ Discover available data sources └─ Use Datasources API ⚠️ MANDATORY: Use Official Valyu SDK Libraries CRITICAL: When writing code that uses the Valyu API, you MUST use the official SDK libraries. NEVER make raw HTTP/fetch calls to the Valyu API endpoints. JavaScript/TypeScript: valyu-js npm install valyu-js # or pnpm add valyu-js import { Valyu } from 'valyu-js' ; const valyu = new Valyu (process. env . VALYU_API_KEY ); // Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deepResearch Python: valyu pip install valyu # or uv add valyu from valyu import Valyu valyu = Valyu(api_key=os.environ.get( "VALYU_API_KEY" )) # Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deep_research Why SDK Over Raw API Calls? Type safety - Full TypeScript/Python type hints for all parameters and responses Automatic retries - Built-in retry logic for transient failures Streaming support - Proper async iterator support for streaming responses Error handling - Structured error types with helpful messages Future compatibility - SDK updates handle API changes automatically ❌ NEVER Do This // DON'T make raw fetch calls const response = await fetch ( 'https://api.valyu.ai/v1/search' , { method : 'POST' , headers : { 'x-api-key' : apiKey, 'Content-Type' : 'application/json' }, body : JSON . stringify ({ query : '...' }) }); ✅ Always Do This // DO use the SDK import { Valyu } from 'valyu-js' ; const valyu = new Valyu (process. env . VALYU_API_KEY ); const response = await valyu. search ({ query : '...' }); 1. Search API Purpose: Find information across web, academic, medical, transportation, financial, news, and proprietary sources. When to Use Finding recent information on any topic Academic research (arXiv, PubMed, bioRxiv, medRxiv) Financial data (SEC filings, earnings reports, stock data) News monitoring and current events Healthcare data (clinical trials, drug labels) Prediction markets (Polymarket, Kalshi) Transportation (UK National Rail, Global Shipping) Basic Usage const response = await valyu. search ({ query : "transformer architecture attention mechanism 2024" , searchType : "all" , maxNumResults : 10 }); Search Types Type Use For all Everything - web, academic, financial, proprietary web General internet content only proprietary Licensed academic papers and research news News articles and current events Key Parameters Parameter (TS/JS) Parameter (Python) Purpose Example query query Search query (under 400 chars) "CRISPR gene editing 2024" searchType search_type Source scope "all" , "web" , "proprietary" , "news" maxNumResults max_num_results Number of results (1-20) 10 includedSources included_sources Limit to specific sources ["valyu/valyu-arxiv", "valyu/valyu-pubmed"] startDate / endDate start_date / end_date Date filtering "2024-01-01" relevanceThreshold relevance_threshold Minimum relevance (0-1) 0.7 Domain-Specific Search Patterns Academic Research: await valyu. search ({ query : "CRISPR therapeutic applications clinical trials" , searchType : "proprietary" , includedSources : [ "valyu/valyu-arxiv" , "valyu/valyu-pubmed" , "valyu/valyu-biorxiv" ], startDate : "2024-01-01" }); Financial Analysis: await valyu. search ({ query : "Apple revenue Q4 2024 earnings" , searchType : "all" , includedSources : [ "valyu/valyu-sec-filings" , "valyu/valyu-earnings-US" ] }); News Monitoring: await valyu. search ({ query : "AI regulation EU" , searchType : "news" , startDate : "2024-06-01" , countryCode : "EU" }); Search Recipes For detailed patterns, see: Basic Search Patterns Academic Search Finance Search News Search Healthcare Search 2. Contents API Purpose: Extract clean, structured content from web pages optimized for LLM processing. When to Use Converting web pages to clean markdown Extracting article text for summarization Parsing documentation for RAG systems Structured data extraction from product pages Processing academic papers Basic Usage const response = await valyu. contents ({ urls : [ "https://example.com/article" ] }); With Summarization const response = await valyu. contents ({ urls : [ "https://arxiv.org/abs/2401.12345" ], summary : "Extract key findings in 3 bullet points" }); Structured Extraction (JSON Schema) const response = await valyu. contents ({ urls : [ "https://example.com/product" ], summary : { type : "object" , properties : { product_name : { type : "string" }, price : { type : "number" }, features : { type : "array" , items : { type : "string" } } }, required : [ "product_name" , "price" ] } }); Key Parameters Parameter (TS/JS) Parameter (Python) Purpose Example urls urls URLs to process (1-10) ["https://example.com"] responseLength response_length Content length "short" , "medium" , "large" , "max" extractEffort extract_effort Extraction quality "normal" , "high" , "auto" summary summary AI summarization true , "instructions" , or JSON schema screenshot screenshot Capture screenshots true Content Recipes For detailed patterns, see: Basic Content Extraction Extraction with Summary Structured Extraction Research Paper Extraction 3. Answer API Purpose: Get AI-powered answers grounded in real-time search results with citations. When to Use Questions requiring current information synthesis Multi-source fact verification Technical documentation questions Research requiring cited sources Structured data extraction from search results Basic Usage const response = await valyu. answer ({ query : "What are the latest developments in quantum computing?" }); With Fast Mode (Lower Latency) const response = await valyu. answer ({ query : "Current Bitcoin price and 24h change" , fastMode : true }); With Custom Instructions const response = await valyu. answer ({ query : "Compare React and Vue for enterprise applications" , systemInstructions : "Provide a balanced comparison with pros and cons. Format as a comparison table." }); With Streaming const stream = await valyu. answer ({ query : "Explain transformer architecture" , streaming : true }); for await ( const chunk of stream) { // Handle: search_results, content, metadata, done, error console . log (chunk); } Structured Output const response = await valyu. answer ({ query : "Apple Q4 2024 financial highlights" , structuredOutput : { type : "object" , properties : { revenue : { type : "string" }, growthRate : { type : "string" }, keyHighlights : { type : "array" , items : { type : "string" } } } } }); Key Parameters Parameter (TS/JS) Parameter (Python) Purpose Example query query Question to answer "What is quantum computing?" fastMode fast_mode Lower latency true systemInstructions system_instructions AI directives "Be concise" structuredOutput structured_output JSON schema {type: "object", ...} streaming streaming Enable SSE streaming true dataMaxPrice data_max_price Dollar limit 1.0 Answer Recipes For detailed patterns, see: Basic Answer Fast Mode Streaming Custom Instructions 4. DeepResearch API Purpose: Generate comprehensive research reports with detailed analysis and citations. When to Use Comprehensive market analysis Literature reviews Competitive intelligence Technical deep dives Topics requiring multi-source synthesis Research Modes Mode Duration Best For fast ~5 minutes Quick lookups, simple questions standard ~10-20 minutes Balanced research (most common) heavy ~90 minutes Comprehensive analysis, complex topics Create Research Task