valyu-best-practices

# 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` ```bash npm install valyu-js # or pnpm add valyu-js ``` ```typescript 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` ```bash pip install valyu # or uv add valyu ``` ```python 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? 1. **Type safety** - Full TypeScript/Python type hints for all parameters and responses 2. **Automatic retries** - Built-in retry logic for transient failures 3. **Streaming support** - Proper async iterator support for streaming responses 4. **Error handling** - Structured error types with helpful messages 5. **Future compatibility** - SDK updates handle API changes automatically ### ❌ NEVER Do This ```typescript // 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 ```typescript // 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 ```typescript 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:** ```typescript 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:** ```typescript await valyu.search({ query: "Apple revenue Q4 2024 earnings", searchType: "all", includedSources: ["valyu/valyu-sec-filings", "valyu/valyu-earnings-US"] }); ``` **News Monitoring:** ```typescript await valyu.search({ query: "AI regulation EU", searchType: "news", startDate: "2024-06-01", countryCode: "EU" }); ``` ### Search Recipes For detailed patterns, see: - [Basic Search Patterns](references/search-recipes/basic-search-all.md) - [Academic Search](references/search-recipes/academic-search.md) - [Finance Search](references/search-recipes/finance-search.md) - [News Search](references/search-recipes/news-search.md) - [Healthcare Search](references/search-recipes/healthcare-and-bio-search.md) --- ## 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 ```typescript const response = await valyu.contents({ urls: ["https://example.com/article"] }); ``` ### With Summarization ```typescript const response = await valyu.contents({ urls: ["https://arxiv.org/abs/2401.12345"], summary: "Extract key findings in 3 bullet points" }); ``` ### Structured Extraction (JSON Schema) ```typescript 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](references/content-recipes/basic-content-extraction-from-web.md) - [Extraction with Summary](references/content-recipes/basic-content-extraction-from-web-with-summary.md) - [Structured Extraction](references/content-recipes/structured-content-extraction-from-web.md) - [Research Paper Extraction](references/content-recipes/extract-content-from-research-paper.md) --- ## 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 ```typescript const response = await valyu.answer({ query: "What are the latest developments in quantum computing?" }); ``` ### With Fast Mode (Lower Latency) ```typescript const response = await valyu.answer({ query: "Current Bitcoin price and 24h change", fastMode: true }); ``` ### With Custom Instructions ```typescript 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 ```typescript 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 ```typescript 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](references/answer-recipes/basic-answer.md) - [Fast Mode](references/answer-recipes/answer-with-fast-mode.md) - [Streaming](references/answer-recipes/answer-with-streaming.md) - [Custom Instructions](references/answer-recipes/answer-with-custom-instructions.md) --- ## 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