Skip to content
valyuAIPublic

About

The Official Valyu Python Package

Resources

Stars

10 stars

Watchers

1 watching

Forks

Latest commit

 

History

243 Commits

Folders and files

Repository files navigation

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
    include_abstracts=True,                         # search the full PubMed abstract corpus
    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
include_abstracts bool False Search PubMed's complete abstract corpus instead of full-text papers
include_image_links bool True When False, image markdown ![alt](url) in result content becomes [Image: alt] and images with no alt text are removed
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"},
        },
    },
)

# Replace image links in the content with their alt text
response = valyu.contents(
    ["https://example.com/article"],
    include_image_links=False,   # ![alt](url) becomes [Image: alt]
)

The include_image_links option (default True) is also available on valyu.search(). When it is False, image markdown ![alt](url) becomes [Image: alt], and images with no alt text are removed.

Answer

Deprecated. The Answer API is deprecated (announced 2026-11-17) and stops working on 2026-12-17, when the endpoint returns HTTP 410. valyu.answer() still works until then but emits a DeprecationWarning. Use DeepResearch with mode="instant", or search() plus your own LLM. See the migration guide.

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
edit(task_id, instruction, ...) Edit a finished report or deliverable
get_edit(task_id, edit_id) Get one edit
list_edits(task_id) List a task's edits
wait_for_edit(task_id, edit_id, ...) Poll until an edit finishes
list_versions(task_id) List report versions
restore_version(task_id, version) Restore an earlier version

Modes. mode is one of "instant", "fast", "standard" (default), "heavy" or "max". "instant" is the quickest and lowest-cost mode and typically finishes in under 30 seconds; it does not support hitl checkpoints and is not available for batches.

task = valyu.deepresearch.create(query="What is the capital of Australia?", mode="instant")
result = valyu.deepresearch.wait(task.deepresearch_id)

Polling. status(), wait() and stream() poll conditionally. When the server returns an ETag, the next poll for that task sends it as If-None-Match; a 304 Not Modified reuses the previous response with no body transferred, and on_progress / stream progress callbacks are not repeated for a 304. When poll_interval is not set, wait() and stream() follow the server's Retry-After hint (clamped to 1-30 seconds, default 5); an explicit poll_interval always wins. Rate limits (429) and server errors (5xx) are retried with jittered exponential backoff. Servers that send no ETag are polled exactly as before.

Edit a finished report

Make small, targeted edits to a finished DeepResearch report or deliverable with a plain-language instruction. Untouched text stays exactly as it was, citations stay consistent, and every edit creates a new version you can restore.

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

if result.editable:
    edit = valyu.deepresearch.edit(
        task.deepresearch_id,
        "Cut the executive summary to 3 bullets and add the Q3 revenue figure with its citation.",
        focus={"section": "Executive Summary", "scope": "strict"},
        base_version=result.version,
        wait_seconds=15,
    )
    if edit.success and edit.status == "running":
        edit = valyu.deepresearch.wait_for_edit(task.deepresearch_id, edit.edit_id)

    if edit.status == "applied":
        print(f"Version {edit.version}: {edit.summary}")
        updated = valyu.deepresearch.status(task.deepresearch_id)
    elif edit.status == "declined":
        print(edit.decline.code, edit.decline.suggestion)
    else:
        print(edit.error_code, edit.error)
  • Target. Edits change the report by default. Pass target={"kind": "deliverable", "deliverable_id": "f_01"} to edit a deliverable file, using the id from the task's deliverables.
  • Focus. focus (a DeepResearchEditFocus or dict) points the edit at a passage (start_char/end_char UTF-16 offsets into the version's output, text, prefix, suffix) or a section heading. scope="strict" rejects any change outside it; the default is "prefer".
  • Citations. citations="stable" (the default) keeps existing citation numbers; "compact" renumbers them by first appearance.
  • Concurrency. Pass base_version (the version from status()) to fail with edit.revision_conflict instead of editing a report that changed since you read it. Pass idempotency_key so a retried request returns the same edit.
  • Outcomes. A finished edit is applied, declined (a normal outcome with decline.code, for example edit.out_of_evidence or edit.rewrite_requested; start a new task for those) or failed (error.code, for example edit.interrupted). A rejected request has success=False and an error_code such as edit.in_progress, edit.task_not_completed or focus.ambiguous (with candidates).
  • Versions. list_versions(task_id) lists every version (version 1 is the original), status(task_id, version=N) reads one, and restore_version(task_id, N) makes version N current again as a new version. No version is deleted.

Guide: https://docs.valyu.ai/guides/deepresearch-editing

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}"),
)

Workflows

Templated DeepResearch starting points - curated by Valyu or created by your org - with typed {variable} placeholders and version history.

# Browse curated workflows
catalog = valyu.workflows.list(scope="valyu", vertical="investment-banking")
for wf in catalog.workflows:
    print(wf.slug, "-", wf.title)

# Run one as a DeepResearch task
task = valyu.deepresearch.create(
    workflow_id="ib-company-profile",
    workflow_params={"company": "NVIDIA (NVDA)"},
)

result = valyu.deepresearch.wait(task.deepresearch_id)
print(result.output)

Create your own:

valyu.workflows.create(
    slug="weekly-competitor-scan",
    title="Weekly Competitor Scan",
    version={
        "prompt": "Summarize the week's most important developments at {company}.",
        "strategy": "Prioritize primary sources: filings, press releases, earnings calls.",
        "report_format": "Bullet-point briefing, grouped by theme.",
        "variables": [{"key": "company", "label": "Company", "required": True}],
    },
)
All Workflows methods
Method Description
list(vertical, scope, q, tags, limit, expand) List available workflows
get(slug, version) Get a workflow's full template
versions(slug) List a workflow's version history
preview(slug, workflow_params, workflow_version) Resolve the template without creating a task
create(slug, title, version, ...) Create an org workflow
update(slug, ..., version, set_current) Update metadata and/or publish a new version
delete(slug) Delete an org workflow

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}")

Search, answer and DeepResearch responses may also carry non-fatal warnings (a list of ResponseWarning with type, message and optional detail), for example when a requested dataset isn't included in your plan and was skipped.

Rate limits

A request that exceeds your plan's rate limit gets back HTTP 429. search(), contents(), answer(), deepresearch.create(), batch.create(), and batch.add_tasks() retry it automatically — a 429 means the request was never accepted or billed, so retrying is always safe. Each retry waits the amount of time the response asks for (capped at 60 seconds), up to max_rate_limit_retries attempts (default 2):

valyu = Valyu(max_rate_limit_retries=5)  # default is 2; use 0 to disable retrying

If every retry is also rate limited, the call still returns its normal response model with success=False, plus a structured rate_limit field:

response = valyu.search("test")

if response.rate_limit:
    print(f"Retry after: {response.rate_limit.retry_after}s")
    print(f"Plan: {response.rate_limit.plan}")
    print(f"Limit: {response.rate_limit.limit}")  # {"endpoint": ..., "requests_per_second": ...}
    print(f"Upgrade: {response.rate_limit.upgrade_url}")   # self-serve plans
    print(f"Contact: {response.rate_limit.contact_url}")   # enterprise plans, instead of upgrade_url

rate_limit is None for any other error. Older API responses that send only a generic rate-limit message leave plan/limit/upgrade_url/contact_url as None too — retry_after is always set.

The one method that raises on an HTTP error (deepresearch.get_assets()) raises a typed RateLimitError instead, carrying the same fields:

from valyu import RateLimitError

try:
    data = valyu.deepresearch.get_assets(task_id, asset_id)
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")

Integrations

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

Links

License

MIT

About

The Official Valyu Python Package

Resources

Stars

10 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages