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

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

Integrations

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

Links

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.12.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Valyu from gravatar.com Valyu

Credits

Author: Valyu

Maintainer: Harvey Yorke

License

MIT License

Requires

Python >=3.6

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

valyu-2.12.0.tar.gz (56.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

valyu-2.12.0-py3-none-any.whl (59.5 kB view details)

Uploaded Python 3

File details

Details for the file valyu-2.12.0.tar.gz.

File metadata

  • Download URL: valyu-2.12.0.tar.gz
  • Upload date:
  • Size: 56.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for valyu-2.12.0.tar.gz
Algorithm Hash digest
SHA256 4d263b552baf29b77892a92136efee53349db089562bd4e22b95ab7225e6c0e3
MD5 7f1e9610d58502cc38e1d77b2daa60f6
BLAKE2b-256 44f03f8b00deb5c913077587ac664eb2710e842648a2bd01b71edaff40760bf1

See more details on using hashes here.

Provenance

The following attestation bundles were made for valyu-2.12.0.tar.gz:

Publisher: publish.yml on valyuAI/valyu-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file valyu-2.12.0-py3-none-any.whl.

File metadata

  • Download URL: valyu-2.12.0-py3-none-any.whl
  • Upload date:
  • Size: 59.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for valyu-2.12.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6d30f2805266e7be892c1a42826f93a2071d1f283729ccb37ef8a7d9f149d53e
MD5 f6d7ab1c37b4fbbba03010beec95586b
BLAKE2b-256 5f0cbe8c909892f5052ab5b91503afad257d17c275b0ce2d11c2cfec6a199b8c

See more details on using hashes here.

Provenance

The following attestation bundles were made for valyu-2.12.0-py3-none-any.whl:

Publisher: publish.yml on valyuAI/valyu-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.12.1

2 files

This release

2.12.0 This release

2 files

2.11.1

2 files

2.11.0

2 files

2.10.0

2 files

2.9.12

2 files

2.9.11

2 files

2.9.10

2 files

2.9.7

2 files

2.9.5

2 files

2.9.4

2 files

2.9.3

2 files

2.9.1

2 files

2.9.0

2 files

2.8.9

2 files

2.8.8

2 files

2.8.7

2 files

2.8.6

2 files

2.8.5

2 files

2.8.4

2 files

2.8.3

2 files

2.8.2

2 files

2.8.1

2 files

2.7.1

2 files

2.7.0

2 files

2.6.1

2 files

2.6.0

2 files

2.5.9

2 files

2.5.8

2 files

2.5.7

2 files

2.5.6

2 files

2.5.5

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.4

2 files

2.4.3

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.6

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page