Struct ProviderPreferences 

pub struct ProviderPreferences {
    pub order: Option<Vec<String>>,
    pub only: Option<Vec<String>>,
    pub ignore: Option<Vec<String>>,
    pub allow_fallbacks: Option<bool>,
    pub require_parameters: Option<bool>,
    pub data_collection: Option<DataCollection>,
    pub zdr: Option<bool>,
    pub sort: Option<ProviderSort>,
    pub preferred_min_throughput: Option<ThroughputThreshold>,
    pub preferred_max_latency: Option<LatencyThreshold>,
    pub max_price: Option<MaxPrice>,
    pub quantizations: Option<Vec<Quantization>>,
}

Provider preferences for OpenRouter routing.

This struct allows you to control which providers are used and how they are prioritized when making requests through OpenRouter.

See: https://openrouter.ai/docs/guides/routing/provider-selection

Example

use rig::providers::openrouter::{ProviderPreferences, ProviderSortStrategy, Quantization};

// Create preferences for zero data retention providers, sorted by throughput
let prefs = ProviderPreferences::new()
    .sort(ProviderSortStrategy::Throughput)
    .zdr(true)
    .quantizations([Quantization::Int8])
    .only(["anthropic", "openai"]);

Fields

order: Option<Vec<String>>

Try these provider slugs in the given order first. If allow_fallbacks: true, OpenRouter may try other providers after this list is exhausted.

only: Option<Vec<String>>

Hard allowlist. Only these provider slugs are eligible.

ignore: Option<Vec<String>>

Blocklist. These provider slugs are never used.

allow_fallbacks: Option<bool>

If false, the router will not use any providers outside what your constraints permit. Default is true.

require_parameters: Option<bool>

If true, only route to providers that support all parameters in your request. Default is false.

data_collection: Option<DataCollection>

Data collection policy. If DataCollection::Deny, restrict routing to providers that do not store user data non-transiently. Default is DataCollection::Allow.

zdr: Option<bool>

If true, restrict routing to Zero Data Retention endpoints only.

sort: Option<ProviderSort>

Sorting strategy. Affects ordering, not strict exclusion. If set, default load balancing is disabled.

preferred_min_throughput: Option<ThroughputThreshold>

Throughput threshold. Endpoints not meeting the threshold are deprioritized.

preferred_max_latency: Option<LatencyThreshold>

Latency threshold. Endpoints not meeting the threshold are deprioritized.

max_price: Option<MaxPrice>

Hard price ceiling. If no provider is at or under, the request fails.

quantizations: Option<Vec<Quantization>>

Restrict routing to providers serving specific quantization levels.

Implementations

impl ProviderPreferences

pub fn new() -> Self

Create a new empty provider preferences struct

pub fn order( self, providers: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Try these provider slugs in the given order first.

If allow_fallbacks is true (default), OpenRouter may try other providers after this list is exhausted.

Example

use rig::providers::openrouter::ProviderPreferences;

let prefs = ProviderPreferences::new()
    .order(["anthropic", "openai"]);

pub fn only( self, providers: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Hard allowlist. Only these provider slugs are eligible.

Example

use rig::providers::openrouter::ProviderPreferences;

let prefs = ProviderPreferences::new()
    .only(["azure", "together"])
    .allow_fallbacks(false);

pub fn ignore( self, providers: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Blocklist. These provider slugs are never used.

Example

use rig::providers::openrouter::ProviderPreferences;

let prefs = ProviderPreferences::new()
    .ignore(["deepinfra"]);

pub fn allow_fallbacks(self, allow: bool) -> Self

Control whether fallbacks are allowed.

If false, the router will not use any providers outside what your constraints permit. Default is true.

pub fn require_parameters(self, require: bool) -> Self

If true, only route to providers that support all parameters in your request.

Default is false, meaning providers may ignore unsupported parameters.

pub fn data_collection(self, policy: DataCollection) -> Self

Set data collection policy.

If Deny, restrict routing to providers that do not store user data non-transiently.

pub fn zdr(self, enable: bool) -> Self

If true, restrict routing to Zero Data Retention endpoints only.

Example

use rig::providers::openrouter::ProviderPreferences;

let prefs = ProviderPreferences::new()
    .zdr(true);

pub fn sort(self, sort: impl Into<ProviderSort>) -> Self

Set the sorting strategy for providers.

If set, default load balancing is disabled and providers are tried deterministically in the resulting order.

Example

use rig::providers::openrouter::{ProviderPreferences, ProviderSortStrategy};

let prefs = ProviderPreferences::new()
    .sort(ProviderSortStrategy::Latency);

pub fn preferred_min_throughput(self, threshold: ThroughputThreshold) -> Self

Set preferred minimum throughput threshold.

Endpoints not meeting the threshold are deprioritized (moved later), not excluded.

Example

use rig::providers::openrouter::{ProviderPreferences, ThroughputThreshold, PercentileThresholds};

// Simple threshold
let prefs = ProviderPreferences::new()
    .preferred_min_throughput(ThroughputThreshold::Simple(50.0));

// Percentile threshold
let prefs = ProviderPreferences::new()
    .preferred_min_throughput(ThroughputThreshold::Percentile(
        PercentileThresholds::new().p90(50.0)
    ));

pub fn preferred_max_latency(self, threshold: LatencyThreshold) -> Self

Set preferred maximum latency threshold.

Endpoints not meeting the threshold are deprioritized, not excluded.

pub fn max_price(self, price: MaxPrice) -> Self

Set maximum price ceiling.

If no eligible provider is at or under the ceiling, the request fails.

pub fn quantizations( self, quantizations: impl IntoIterator<Item = Quantization>, ) -> Self

Restrict routing to providers serving specific quantization levels.

Example

use rig::providers::openrouter::{ProviderPreferences, Quantization};

let prefs = ProviderPreferences::new()
    .quantizations([Quantization::Int8, Quantization::Fp16]);

pub fn zero_data_retention(self) -> Self

Convenience: Enable Zero Data Retention

pub fn fastest(self) -> Self

Convenience: Sort by throughput (higher tokens/sec first)

pub fn cheapest(self) -> Self

Convenience: Sort by price (cheapest first)

pub fn lowest_latency(self) -> Self

Convenience: Sort by latency (lower latency first)

pub fn to_json(&self) -> Value

Convert to JSON value for use in additional_params

Trait Implementations

impl Clone for ProviderPreferences

fn clone(&self) -> ProviderPreferences

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProviderPreferences

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ProviderPreferences

fn default() -> ProviderPreferences

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ProviderPreferences

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ProviderPreferences

fn eq(&self, other: &ProviderPreferences) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ProviderPreferences

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ProviderPreferences