Skip to content

feat(tool): add Sofya as a selectable web_search provider - #560

Open
yusufgurdogan wants to merge 2 commits into
vllm-project:mainfrom
yusufgurdogan:add-sofya-web-search
Open

yusufgurdogan wants to merge 2 commits into
vllm-project:mainfrom
yusufgurdogan:add-sofya-web-search

Conversation

@yusufgurdogan

Copy link
Copy Markdown

Summary

Adds Sofya (API docs), a web search API for AI agents, as a selectable web_search provider beside You.com, Brave Search, Tavily, SearXNG, Serply and Keenable. It follows the shape of the Tavily and Keenable providers (#329, #507). There is no linked issue.

Disclosure: I work on Sofya. Happy to change the variable name, the default depth or the docs wording.

Changes by API

API What changed
Responses (/v1/responses) no wire change; web_search can run on Sofya with AGENTIC_WEB_SEARCH_PROVIDER=sofya and SOFYA_API_KEY
Messages (/v1/messages) no wire change; web_search_20250305 runs on the same configured provider

How the shared tool contract maps to Sofya's POST /v1/search:

  • The key goes in Authorization: Bearer, never in the body, and Debug stays redacted through the shared ApiKey.
  • Every query is one search_depth: "snippets", topic: "general" request, so all hits land in web and news stays empty.
  • count (or search_context_size) is clamped to 20 as max_results.
  • freshness is sent as Sofya's freshness: day, week, month, year, or YYYY-MM-DD:YYYY-MM-DD. Both sides treat the range as inclusive, so the dates are not widened.
  • Domain filters keep the usual precedence and conflict check. They are sent as include_domains / exclude_domains and re-checked on the response by the shared DomainFilter. Sofya takes at most 10 bare host names per list and answers 422 otherwise, so only such entries are sent and the rest is left to the gateway filter.
  • country, language, safesearch and the You.com-specific arguments have no Sofya parameter and are logged as ignored at debug level.
  • Response: the description is description (the snippet), falling back to content; page_age is published_date; blank URLs are dropped; a null results is empty. metadata[] carries "provider": "sofya", the X-Request-Id response header as search_uuid and elapsed_ms as latency in seconds.
  • Errors: 401/403 name SOFYA_API_KEY without echoing anything secret. 402 (out of credits, or a key limit) and 429 (with Retry-After) are never retried. Other statuses include the upstream body.

WebSearchHandler::from_config now computes the provider's concurrency ceiling once instead of once per match arm. The values are the same; without it the new arm puts web_search/mod.rs at 507 production lines, over the 500 limit. If you prefer an exception entry in .rust-file-sizes.json instead, I will switch.

Flow

flowchart LR
    M[model calls web_search] --> H[WebSearchHandler]
    H -->|provider = sofya| S[SofyaSearchProvider, new]
    S -->|POST /v1/search, Bearer key| A[Sofya API]
    A -->|results, elapsed_ms, X-Request-Id| S
    S -->|DomainFilter re-check| H
    H --> O[web_search_call output]
Loading

New modules

  • tool/web_search/sofya.rs: request shaping and response mapping for Sofya. It sits next to tavily.rs and keenable.rs and implements the same WebSearchProvider trait.
Class diagram
classDiagram
    class WebSearchProvider {
        <<trait>>
        search(query, args, config)
        max_concurrent_requests()
    }
    class SofyaSearchProvider {
        client
        api_key: ApiKey
        base_url
        max_concurrent_requests
    }
    class SofyaSearchRequest {
        body: SofyaSearchBody
        domain_filter: DomainFilter
    }
    class SofyaSearchResponse {
        results: Vec~SofyaResult~
        elapsed_ms
    }
    WebSearchProvider <|.. SofyaSearchProvider
    WebSearchHandler --> WebSearchProvider
    SofyaSearchProvider ..> SofyaSearchRequest : builds from WebSearchArguments
    SofyaSearchProvider ..> SofyaSearchResponse : parses
    SofyaSearchResponse ..> WebSearchProviderResponse : maps to
    WebSearchProviderKind --> SofyaSearchProvider : Sofya selects
Loading

Test Plan

  • No recordings added: the OpenAI and Anthropic wire shapes do not change, and the cassette recorders capture those APIs, not a search backend. Keenable (feat(tool): add Keenable as a selectable web_search provider #507) added none either. I cannot run the OpenAI-side recorders, so if you want a recording for this, please say which scenario.
  • 12 unit tests in sofya.rs cover: redacted Debug and default/override base URL; the missing-key error; endpoint and bearer header; body shape, clamping and ignored arguments; freshness keywords and ranges; which domain entries are forwarded and the cap of 10; config filter precedence and the conflict check; response mapping with the content fallback, blank URLs, null results and the response-side domain filter.
  • config.rs kind assertions and the unknown-provider message now include sofya; web_search_config_selects_sofya_from_environment, plus a keenable -> sofya case in the provider-switch loop.
  • Live check with a real key against the Sofya API, through SofyaSearchProvider::search: a plain query, freshness: week with an allowlist that mixes host names and a path entry, a date range with 12 blocked domains, and an invalid key. Results, page_age, search_uuid and latency came back as mapped; the invalid key gave Sofya rejected the API key (401 Unauthorized); check SOFYA_API_KEY. The same body with a path entry or 11 domains sent directly returns 422, which is why those are not forwarded.
  • cargo fmt --all -- --check: clean. cargo clippy -p agentic-server-core -p agentic-server --all-targets -- -D warnings: clean. cargo test -p agentic-server-core -p agentic-server: 3127 passed, 0 failed, 25 ignored. pre-commit run --all-files: all hooks pass, including rust-file-sizes.

Adds Sofya (https://sofya.co) beside You.com, Brave Search, Tavily,
SearXNG, Serply and Keenable, selected with
AGENTIC_WEB_SEARCH_PROVIDER=sofya and SOFYA_API_KEY.

Requests are POST /v1/search with a bearer key at the snippets depth.
count is clamped to 20, freshness and domain filters are forwarded to
Sofya's own parameters, and domain filters are re-checked on the
response. Sofya takes at most 10 bare host names per list, so only such
entries are sent and the rest is left to the gateway filter.

WebSearchHandler::from_config computes the provider's concurrency
ceiling once instead of once per match arm, which keeps
web_search/mod.rs within the production file size limit.

Signed-off-by: Yusuf Gürdoğan <yusufgurdogan@protonmail.com>
Signed-off-by: Yusuf Gürdoğan <yusufgurdogan@protonmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant