Python SDK - Valyu

The Valyu SDK provides access to the following features:

Deep Search - Search and retrieve relevant content from proprietary and public sources

Getting Started

Install the Valyu SDK

pip install valyu

And then instantiate the Valyu client - you can obtain your API key here ($10 free credits cus we are legends)

from valyu import Valyu

# The SDK will automatically use VALYU_API_KEY from environment
valyu = Valyu()

# Alternatively, you can still pass it explicitly
valyu = Valyu(api_key="your-api-key-here")

Quick Start

Let’s see how to use the deep search feature with a simple example:

main.py

from valyu import Valyu

# Initialize the client
valyu = Valyu()

# Search for information about a specific topic
response = valyu.search(
    "What are the benefits of renewable energy?",
    search_type="all",            # Search both proprietary and web sources
    max_num_results=5,            # Limit to top 5 results
    relevance_threshold=0.5,      # Only return results with >50% relevance
    max_price=30.0,               # Maximum cost in dollars
    is_tool_call=True             # True for AI agents/tools, False for direct user queries
)

# Process the results
print(response)

Advanced Usage

Here’s an example using more v2 parameters for targeted searches:

# AI Agent making a search (tool call)
financial_response = valyu.search(
    "Pfizer stock price since COVID-19 outbreak",
    search_type="proprietary",
    max_num_results=1,
    relevance_threshold=0.5,
    max_price=30.0,
    is_tool_call=True  # True: AI agent/tool is making this search
)

# Direct user query (not through an AI agent)
user_response = valyu.search(
    "What are the latest developments in quantum computing?",
    search_type="all",
    max_num_results=5,
    relevance_threshold=0.5,
    max_price=30.0,
    is_tool_call=False  # False: Direct user query, not through AI agent
)

# Academic research with specific sources (AI agent)
academic_response = valyu.search(
    "CRISPR gene editing safety studies",
    search_type="proprietary",
    max_num_results=8,
    relevance_threshold=0.6,
    max_price=30.0,
    category="biomedical research",
    included_sources=["valyu/valyu-pubmed"],
    excluded_sources=["reddit.com", "quora.com"],
    response_length="medium",  # 50k characters per result
    country_code="US",  # Bias results toward US sources
    is_tool_call=True  # True: Part of an AI agent workflow
)

Input Parameters:

Parameter	Type	Description	Default
query	str	The input query to be processed.	Required
search_type	Literal[‘all’, ‘proprietary’, ‘web’]	Specifies the type of search to be performed. ‘all’ includes both proprietary and web sources, ‘proprietary’ searches over Valyu indices, and ‘web’ is just web search.	”all”
max_num_results	int	The maximum number of results to be returned (1-20).	5
relevance_threshold	float	The minimum relevance score required for a result to be included (0.0-1.0).	0.5
max_price	float	Maximum cost in dollars for 1000 retrievals.	30.0
is_tool_call	bool	Set to `True` when called by AI agents/tools (optimized for LLM consumption). Set to `False` for direct user queries.	True
category	str	Natural language category to guide search context (optional).	None
included_sources	List[str]	List of specific sources to search within (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., ‘https://valyu.network/blog’ or ‘valyu.network/blog’), only that specific path will be searched. For entire domains, use either the domain name (e.g., ‘valyu.network’) or the base URL (e.g., ‘https://valyu.network’) (optional).	None
excluded_sources	List[str]	List of specific sources to exclude from search (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., ‘https://valyu.network/blog’ or ‘valyu.network/blog’), only that specific path will be excluded. For entire domains, use either the domain name (e.g., ‘valyu.network’) or the base URL (e.g., ‘https://valyu.network’) (optional).	None
response_length	Union[int, str]	Controls content length per result. Integer for character count or predefined values: “short” (25k), “medium” (50k), “large” (100k), “max” (full) (optional).	“short”
country_code	str	2-letter ISO country code to bias search results to a specific country (optional).	None
start_date	str	Start date for time filtering in YYYY-MM-DD format (optional).	None
end_date	str	End date for time filtering in YYYY-MM-DD format (optional).	None

Example Response:

{
    "success": True,
    "error": "",
    "tx_id": "tx_4cce8eed-7864-42ec-b385-dee7d5b14936",
    "query": "What are agentic search-enhanced large reasoning models?",
    "results": [
        {
            "title": "2501.05366",
            "url": "https://arxiv.org/abs/2501.05366",
            "content": "# Search-o1: Agentic Search-Enhanced Large Reasoning Models...",
            "source": "valyu/valyu-arxiv",
            "price": 0.0005,
            "length": 17442,
            "image_url": {
                "_page_1_Figure_0.jpeg": "https://..."
            },
            "data_type": "unstructured",
            "relevance_score": 0.77734375
        }
        // Additional results...
    ],
    "results_by_source": {
        "web": 1,
        "proprietary": 4
    },
    "total_results": 5,
    "total_characters": 81208
}

Output Parameters:

Parameter	Type	Description
success	boolean	Indicates if the request was successful
error	string	Error message if any
tx_id	string	Unique transaction ID for the request
query	string	The processed query string
results	array	Array of result objects (see Results Object table below)
results_by_source	object	Count of results by source type (web/proprietary)
total_results	integer	Total number of results returned
total_characters	integer	Total number of characters in results

Results Object:

Parameter	Type	Description
id	string	Unique identifier for the result (optional)
title	string	Title of the result
url	string	URL of the source
content	string	The actual text chunk of the result
source	string	Source identifier (e.g., “valyu/valyu-arxiv”, “valyu/valyu-stocks-US”)
price	float	Cost of this specific text chunk in USD
length	integer	Character length of the content
image_url	object	Map of image identifiers to image URLs, can be used to render in frontend AI applications
data_type	string	Type of data, either “unstructured” or “structured”. If structured (e.g. for stock data) it will be a string JSON object
source_type	string	Type of source (e.g., “paper”, “data”, “web”, “book”)
relevance_score	float	Relevance score between 0 and 1
publication_date	string	Publication date in YYYY-MM-DD format (for source_type “paper” and “book”)
doi	string	Digital Object Identifier (for source_type “paper” and “book”)
citation	string	Formatted citation string (for source_type “paper”)
citation_count	integer	Number of citations (for source_type “paper”)
authors	array	List of author names (for source_type “paper” and “book”)
references	string	References section content (for source_type “paper” and “book”)

SDKs

​Getting Started

​Quick Start

​Advanced Usage

​Input Parameters:

​Example Response:

​Output Parameters:

​Results Object: