Skip to content

README.md

Latest commit

 

History

History
231 lines (171 loc) · 6.25 KB

README.md

File metadata and controls

231 lines (171 loc) · 6.25 KB

Valyu Python SDK

PyPI version License: MIT

Search and research APIs built for AI agents. Access web and proprietary data sources through Search, extract content from URLs, generate grounded answers, and run multi-step research with DeepResearch - all through a single SDK.

Documentation | API Reference | Platform

Installation

pip install valyu

Quick Start

from valyu import Valyu

valyu = Valyu()  # uses VALYU_API_KEY env var

response = valyu.search(
    "latest advances in transformer architectures",
    max_num_results=5,
    search_type="all",
)

for result in response.results:
    print(result.title, result.url)

Get $10 free credits when you sign up at platform.valyu.ai. No credit card required.

APIs

Search

Search across web and proprietary data sources with a single query.

response = valyu.search(
    "CRISPR gene therapy clinical trials 2026",
    search_type="proprietary",                     # "all", "web", or "proprietary"
    max_num_results=10,                            # 1-20 results
    included_sources=["valyu/valyu-pubmed"],        # filter to specific sources
    start_date="2026-01-01",                       # date filtering
    end_date="2026-12-31",
)
All search parameters
Parameter Type Default Description
query str required Search query
search_type str "all" "all", "web", or "proprietary"
max_num_results int 10 Results to return (1-20)
max_price int 30 Max price per thousand queries (CPM)
relevance_threshold float 0.5 Min relevance score (0-1)
included_sources List[str] None Sources to search
excluded_sources List[str] None Sources to exclude
start_date str None Start date (YYYY-MM-DD)
end_date str None End date (YYYY-MM-DD)
country_code str None Country filter (e.g. "US", "GB")
response_length str | int None "short", "medium", "large", "max", or character count
category str None Category filter
fast_mode bool False Faster results, shorter content

Contents

Extract clean, structured content from URLs. Supports sync (1-10 URLs) and async (up to 50 URLs) modes.

# Basic extraction
response = valyu.contents(["https://arxiv.org/abs/2301.00001"])

# With AI summarization
response = valyu.contents(
    ["https://example.com/article"],
    summary=True,
    response_length="medium",
)

# Structured data extraction with JSON schema
response = valyu.contents(
    ["https://en.wikipedia.org/wiki/OpenAI"],
    summary={
        "type": "object",
        "properties": {
            "company_name": {"type": "string"},
            "founded_year": {"type": "integer"},
        },
    },
)

Answer

AI-generated answers grounded by Valyu's search. Supports streaming.

response = valyu.answer(
    "What are the side effects of metformin?",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed"],
)

print(response.contents)        # AI-generated answer
print(response.search_results)  # Source citations

DeepResearch

Multi-step research agent that produces comprehensive reports with citations.

# Start a research task
task = valyu.deepresearch.create(
    input="Compare CRISPR and base editing approaches for sickle cell disease",
    model="heavy",
    output_formats=["markdown", "pdf"],
)

# Wait for completion with progress
def on_progress(status):
    print(f"Step {status.progress.current_step}/{status.progress.total_steps}")

result = valyu.deepresearch.wait(task.deepresearch_id, on_progress=on_progress)

print(result.output)   # Markdown report
print(result.pdf_url)  # PDF download link
All DeepResearch methods
Method Description
create(...) Start a new research task
status(task_id) Get task status
wait(task_id, ...) Poll until completion
stream(task_id, ...) Stream real-time updates
list(api_key_id, limit) List research tasks
update(task_id, instruction) Add follow-up instruction
cancel(task_id) Cancel a running task
delete(task_id) Delete a task
toggle_public(task_id, is_public) Toggle public access

Batch

Run multiple DeepResearch tasks in parallel.

batch = valyu.batch.create(
    name="Q1 Analysis",
    mode="fast",
    output_formats=["markdown"],
)

valyu.batch.add_tasks(batch.batch_id, tasks=[
    {"query": "Analyze recent SPAC performance"},
    {"query": "Review semiconductor supply chain trends"},
])

result = valyu.batch.wait_for_completion(
    batch.batch_id,
    on_progress=lambda b: print(f"{b.counts.completed}/{b.counts.total}"),
)

Data Sources

List available data sources programmatically.

sources = valyu.datasources.list()
categories = valyu.datasources.categories()

Authentication

export VALYU_API_KEY="your-api-key"

Or pass directly:

valyu = Valyu(api_key="your-api-key")

Type Safety

All request and response models use Pydantic v2:

from valyu.types.response import SearchResult, SearchResponse
from valyu.types.contents import ContentsResponse
from valyu.types.answer import AnswerSuccessResponse

Error Handling

response = valyu.search("test")

if not response.success:
    print(f"Error: {response.error}")
    print(f"tx_id: {response.tx_id}")

Integrations

Valyu works with LangChain, OpenAI, Anthropic, MCP, and more. See docs.valyu.ai for integration guides.

Links

License

MIT