LlamaIndex

Add Valyu search and URL extraction to LlamaIndex apps and agents with ValyuToolSpec, then pass returned documents into your retrieval or agent pipeline.

Add web and specialist retrieval to LlamaIndex through ValyuToolSpec. Use Search to find evidence and Contents to read known URLs, then pass the returned documents to your existing retrieval or agent pipeline.

The package includes two main functions:

• search(): Search operations with comprehensive parameter control
• get_contents(): Extract clean content from specific URLs

Installation

Install the official LlamaIndex Valyu package:

pip install llama-index-tools-valyu

Configure your credentials by setting the following environment variable:

export VALYU_API_KEY="your-api-key-here"

Basic usage

Using ValyuToolSpec for search

import os
from llama_index.tools.valyu import ValyuToolSpec

# Initialize the tool with comprehensive configuration
valyu_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    verbose=True,
    # Search API parameters
    relevance_threshold=0.5,  # Minimum relevance score
    fast_mode=False,  # Quality vs speed trade-off
    included_sources=None,  # Optional source filtering
    excluded_sources=None,  # Optional source exclusion
    response_length=None,  # Content length control
    country_code=None,  # Geographic bias
)

# Perform a search
search_results = valyu_tool.search(
    query="What are agentic search-enhanced large reasoning models?",
    search_type="all",  # "all", "web", or "proprietary"
    max_num_results=5,
    start_date=None,  # Optional time filtering
    end_date=None,
    fast_mode=None  # Uses tool default if None
)

print("Search Results:")
for doc in search_results:
    print(f"Title: {doc.metadata['title']}")
    print(f"Content: {doc.text[:200]}...")
    print(f"Source: {doc.metadata['url']}")
    print(f"Relevance: {doc.metadata['relevance_score']}")
    print("---")

Using ValyuToolSpec for Content Extraction

import os
from llama_index.tools.valyu import ValyuToolSpec

# Initialize tool with content extraction configuration
valyu_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    verbose=True,
    contents_summary=True,  # Enable AI summarization
    contents_extract_effort="high",  # Thorough extraction
    contents_response_length="medium",  # More detailed content
)

# Extract content from URLs
urls = [
    "https://arxiv.org/abs/1706.03762",  # Attention is All You Need paper
    "https://en.wikipedia.org/wiki/Transformer_(machine_learning_model)"
]

content_results = valyu_tool.get_contents(urls=urls)

print("Extracted Content:")
for doc in content_results:
    print(f"URL: {doc.metadata['url']}")
    print(f"Title: {doc.metadata['title']}")
    print(f"Content: {doc.text[:300]}...")
    if 'summary' in doc.metadata:
        print(f"Summary: {doc.metadata['summary']}")
    print("---")

Using with LlamaIndex OpenAI Agents

The following example uses the llama-index-agent-openai integration. Install it with pip install llama-index-agent-openai and set OPENAI_API_KEY before running:

import os
from llama_index.agent.openai import OpenAIAgent
from llama_index.tools.valyu import ValyuToolSpec

# Initialize Valyu tool with comprehensive configuration
valyu_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    fast_mode=True,  # Enable fast mode for quicker responses
    # Contents API configuration
    contents_summary=True,  # Enable AI summarization for content extraction
    contents_extract_effort="normal",  # Extraction thoroughness
    contents_response_length="medium",  # Content length per URL
)

# Create OpenAI agent with Valyu tools
agent = OpenAIAgent.from_tools(
    valyu_tool.to_tool_list(),
    verbose=True,
)

# Example 1: search query
print("=== Search Example ===")
search_response = agent.chat(
    "What are the key considerations and empirical evidence for implementing statistical arbitrage strategies using cointegrated pairs trading, specifically focusing on the optimal lookback period for calculating correlation coefficients and the impact of transaction costs on strategy profitability in high-frequency trading environments?"
)
print(search_response)

# Example 2: URL content extraction
print("\n=== URL Content Extraction Example ===")
content_response = agent.chat(
    "Please extract and summarize the content from these URLs: https://arxiv.org/abs/1706.03762 and https://en.wikipedia.org/wiki/Transformer_(machine_learning_model)"
)
print(content_response)

Advanced configuration

ValyuToolSpec parameters

Set search defaults at initialization, override per call:

valyu_tool = ValyuToolSpec(
    api_key="your-api-key",
    relevance_threshold=0.5,  # 0.0-1.0
    fast_mode=False,  # quality vs speed
    included_sources=["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
    response_length="medium",  # "short", "medium", "large", "max", or int
    country_code="US",  # 2-letter ISO code
    # Contents API defaults
    contents_summary=True,
    contents_extract_effort="high",  # "normal", "high", "auto"
    contents_response_length="large",
)

results = valyu_tool.search(
    query="quantum computing breakthroughs 2024",
    search_type="all",  # "all", "web", or "proprietary"
    max_num_results=10,  # 1-20 (up to 100 with a special API key)
    start_date="2024-01-01",
    end_date="2024-12-31",
)

get_contents(urls=[...]) extracts clean content from URLs (max 10 per request).

Steer the agent with a system prompt

Pass a system_prompt to your agent: use search_type="all" for broad coverage (web + proprietary), or "web" for current events only; raise relevance_threshold (0.6+) for precision; cite sources; use natural-language queries, not operators. See the Prompting Guide.

Custom query engines and retrievers

Wrap ValyuToolSpec.search() in a CustomQueryEngine or BaseRetriever to plug Valyu into existing LlamaIndex pipelines - call search() in custom_query/_retrieve and map each result doc (with doc.metadata['relevance_score']) into your response or NodeWithScore objects.

Additional resources

LlamaIndex Valyu Tool

Official LlamaIndex tool documentation

API Reference

Complete Valyu API documentation

LlamaHub

Valyu tool on LlamaHub

Get API Key

Sign up for $10 free credits ($20 with a company email)