Support collection:<name> sources in Python SDK validation

[dominikusbrian]

Summary

• Added support for Valyu collection source filters such as collection:my-sources in Python SDK source validation.
• Updated source-format help text to document collection: as a valid included_sources format.
• Added regression coverage so Valyu.search(..., included_sources=["collection:my-sources"]) does not fail client-side validation before reaching the API.

Task Context

Repo	valyu-py
Observed version	v2.9.10
Category	SDK/API parity
Severity	medium

Problem

The Valyu platform and docs show collections as valid included_sources values:

from valyu import Valyu

 valyu = Valyu()
 response = valyu.search(
     query="your search query",
     included_sources=["collection:my-sources"]
 )

However, even in v2.9.10, the Python SDK source validator does not include collection references as an accepted source format. The validator accepts domains, domain paths, URLs, and dataset names, but not collection:.

Current SDK behavior rejects collection sources before the request reaches the API:

Invalid source format(s): collection:my-sources

Sources must be formatted as one of:
• Domain
• Domain with path
• URL with path
• Dataset name

What Is Missing In v2.9.10

v2.9.10 still appears to be missing:

• validation support for collection: source strings
• collection examples in get_source_format_examples()
• collection-aware validation error text
• regression tests covering collection sources in included_sources
• SDK-level request-building coverage confirming collection sources pass through to the API

Expected Behavior

collection: should be accepted as a valid source string for included_sources, consistent with platform-generated API examples and documentation.

Example:

  response = valyu.search(
      query="example query",
      included_sources=["collection:my-sources"],
  )

should not fail SDK validation.

Proposed Minimal Fix

In valyu/validation.py, update validate_source() to accept collection references:

if source.startswith("collection:") and len(source) > len("collection:"):
     return True

Also update get_source_format_examples() / format_validation_error() so the error message includes:

Collection: collection:my-sources, collection:research-sources

Suggested Regression Test

Add a test covering collection validation:

  def test_collection_source_is_valid():
      assert validate_source("collection:my-sources")
      ok, invalid = validate_sources(["collection:my-sources"])
      assert ok
      assert invalid == []

Add SDK-level request-building coverage to verify included_sources=["collection:my-sources"] reaches the request payload without client-side validation failure.

Attachments

None