Skip to content
YosoiDocs

Search

Search combines query intent, provider routing, and per-provider outcomes in one operation.

  1. Choose providers and limits through Policy.
  2. Submit a query.
  3. Inspect each provider outcome.
  4. Fetch selected URLs through Requests.

Search returns candidates; fetching their destination pages is a separate step.

One provider can succeed while another is challenged or unavailable. Preserve those outcomes so your application can explain what it found.

Current built-in provider routes are previews pending certification.

use std::error::Error;
use yosoi::prelude as ys;
use ys::policy::search::{Provider, Search};

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn Error>> {
    let policy = ys::Policy {
        search: Search::new([Provider::Bing])?,
        ..ys::Policy::default()
    };
    let request = ys::search::new("rust sdk")?.bind(&policy);
    request.validate()?; // Does not contact a provider.
    let response = request.send().await?;
    for provider in response.providers() {
        match provider.outcome() {
            ys::search::ProviderOutcome::Results(page) => {
                for hit in page.hits() {
                    println!("{}", hit.url());
                }
            }
            outcome => println!("{outcome:?}"),
        }
    }
    Ok(())
}

Read the per-operation result before using its discovered URLs. This excerpt uses the public facade and explicit Policy.

import asyncio
import yosoi as ys
from yosoi.policy import Policy, ProviderSelection, Search

async def main():
    policy = Policy(search=Search(providers=[ProviderSelection(provider="bing")]))
    request = ys.search.new("rust sdk").bind(policy)
    request.check()
    response = await request.send()
    for provider in response.providers:
        print(provider.provider, provider.outcome)

asyncio.run(main())

The Python variant uses the same provider or discovery choices. Keep attempt and termination information alongside selected URLs.

The example uses an async application entry point. Provider failures remain typed outcomes; preparation and initialization failures are returned as errors.

Try CLI Search for a terminal example. Exact Rust signatures belong in the generated API reference.

Use Requests to acquire a chosen destination and Contracts to extract a typed Rust record. Search does not fetch its result URLs automatically. The Python SDK has a runnable Search review example and a Pydantic Contract surface. Python locates and groups evidence through the native SDK, then validates Contract records through Pydantic. The Python parity report keeps those typed record rules separate from Rust RuntimeContract conformance.