Skip to main content

rig_core/providers/openrouter/
extension.rs

1//! OpenRouter's typed request options and reply extras. Every option is
2//! in the shared section, so one entry serves the Chat and the Responses
3//! route alike.
4//!
5//! ```
6//! use rig_core::completion::CompletionRequest;
7//! use rig_core::providers::openrouter::extension::{
8//!     ModelFallbacks, OpenRouterOptions, ProviderPreferences,
9//! };
10//!
11//! # fn run() -> Result<(), Box<dyn std::error::Error>> {
12//! let options = OpenRouterOptions::new()
13//!     .provider(ProviderPreferences::new().only(["anthropic"]).zdr(true))
14//!     .models(ModelFallbacks::new(["openai/gpt-4o-mini"])?);
15//! let request = CompletionRequest::new("hi").provider_option(options);
16//! # let _ = request;
17//! # Ok(())
18//! # }
19//! ```
20
21use std::collections::BTreeMap;
22
23use serde::{Deserialize, Serialize};
24use serde_json::{Map, Value};
25
26use crate::completion::provider_options::reply_field;
27use crate::completion::{ExtensionOptions, ProviderExtension, ReplyExtras};
28use crate::message::Api;
29
30/// OpenRouter's extension marker.
31#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
32pub struct OpenRouterExt;
33
34impl ProviderExtension for OpenRouterExt {
35    const PROVIDER: &'static str = super::PROVIDER_NAME;
36    type Options = OpenRouterOptions;
37    type Extras = OpenRouterExtras;
38}
39
40/// OpenRouter's request options, all sent on every route.
41#[non_exhaustive]
42#[derive(Clone, Debug, Default, PartialEq, Serialize)]
43pub struct OpenRouterOptions {
44    /// The fields every route takes.
45    #[serde(rename = "*")]
46    pub shared: OpenRouterShared,
47}
48
49/// The fields OpenRouter takes on every route.
50#[non_exhaustive]
51#[derive(Clone, Debug, Default, PartialEq, Serialize)]
52pub struct OpenRouterShared {
53    /// Which upstream providers may serve the request, and in what order.
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub provider: Option<ProviderPreferences>,
56    /// The models tried after the request's own, in order.
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub models: Option<ModelFallbacks>,
59    /// Plugins such as `{"id": "web"}`.
60    #[serde(skip_serializing_if = "Vec::is_empty")]
61    pub plugins: Vec<Value>,
62    /// Groups requests into one session in OpenRouter's logs.
63    #[serde(skip_serializing_if = "Option::is_none")]
64    pub session_id: Option<String>,
65    /// String pairs attached to the request.
66    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
67    pub metadata: BTreeMap<String, String>,
68    /// Reasoning fields sent beside the mapped effort.
69    #[serde(skip_serializing_if = "ReasoningExtra::is_empty")]
70    pub reasoning: ReasoningExtra,
71    /// Sample from the `k` most likely tokens.
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub top_k: Option<u32>,
74    /// The minimum probability of a token, relative to the most likely one.
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub min_p: Option<f64>,
77    /// Top-a sampling.
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub top_a: Option<f64>,
80    /// Penalizes tokens already in the prompt and the output.
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub repetition_penalty: Option<f64>,
83    /// A stable id of the end user.
84    #[serde(skip_serializing_if = "Option::is_none")]
85    pub user: Option<String>,
86}
87
88/// The `reasoning` fields OpenRouter takes beside the effort or budget the
89/// generation options map.
90#[non_exhaustive]
91#[derive(Clone, Debug, Default, PartialEq, Serialize)]
92pub struct ReasoningExtra {
93    /// Reason, but leave the reasoning out of the reply.
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub exclude: Option<bool>,
96    /// How much of the reasoning the reply summarizes.
97    #[serde(skip_serializing_if = "Option::is_none")]
98    pub summary: Option<ReasoningSummary>,
99}
100
101impl ReasoningExtra {
102    fn is_empty(&self) -> bool {
103        self.exclude.is_none() && self.summary.is_none()
104    }
105}
106
107/// How much of the reasoning a reply summarizes.
108#[non_exhaustive]
109#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
110#[serde(rename_all = "lowercase")]
111pub enum ReasoningSummary {
112    /// The provider decides.
113    Auto,
114    /// A short summary.
115    Concise,
116    /// A detailed summary.
117    Detailed,
118}
119
120impl OpenRouterOptions {
121    /// No option set.
122    pub fn new() -> Self {
123        Self::default()
124    }
125
126    /// Route by `preferences`.
127    pub fn provider(mut self, preferences: ProviderPreferences) -> Self {
128        self.shared.provider = Some(preferences);
129        self
130    }
131
132    /// Fall back to `models`, in order, after the request's own model.
133    pub fn models(mut self, models: ModelFallbacks) -> Self {
134        self.shared.models = Some(models);
135        self
136    }
137
138    /// Add `plugin`, such as `{"id": "web"}`.
139    pub fn plugin(mut self, plugin: Value) -> Self {
140        self.shared.plugins.push(plugin);
141        self
142    }
143
144    /// Group the request under session `id`.
145    pub fn session_id(mut self, id: impl Into<String>) -> Self {
146        self.shared.session_id = Some(id.into());
147        self
148    }
149
150    /// Attach the metadata pair `key`, `value`.
151    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
152        self.shared.metadata.insert(key.into(), value.into());
153        self
154    }
155
156    /// Reason but leave the reasoning out of the reply when `exclude`.
157    pub fn reasoning_exclude(mut self, exclude: bool) -> Self {
158        self.shared.reasoning.exclude = Some(exclude);
159        self
160    }
161
162    /// Summarize the reasoning at `summary`.
163    pub fn reasoning_summary(mut self, summary: ReasoningSummary) -> Self {
164        self.shared.reasoning.summary = Some(summary);
165        self
166    }
167
168    /// Sample from the `k` most likely tokens.
169    pub fn top_k(mut self, k: u32) -> Self {
170        self.shared.top_k = Some(k);
171        self
172    }
173
174    /// Set the minimum relative token probability.
175    pub fn min_p(mut self, p: f64) -> Self {
176        self.shared.min_p = Some(p);
177        self
178    }
179
180    /// Set top-a sampling.
181    pub fn top_a(mut self, a: f64) -> Self {
182        self.shared.top_a = Some(a);
183        self
184    }
185
186    /// Set the repetition penalty.
187    pub fn repetition_penalty(mut self, penalty: f64) -> Self {
188        self.shared.repetition_penalty = Some(penalty);
189        self
190    }
191
192    /// Name the end user.
193    pub fn user(mut self, user: impl Into<String>) -> Self {
194        self.shared.user = Some(user.into());
195        self
196    }
197}
198
199impl ExtensionOptions for OpenRouterOptions {
200    type Ext = OpenRouterExt;
201}
202
203/// A non-empty list of fallback models.
204#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
205#[serde(transparent)]
206pub struct ModelFallbacks(Vec<String>);
207
208/// A fallback list with no model.
209#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
210#[error("model fallbacks need at least one model")]
211pub struct EmptyFallbacks;
212
213impl ModelFallbacks {
214    /// The models tried, in order, after the request's own.
215    ///
216    /// # Errors
217    ///
218    /// When `models` is empty.
219    pub fn new(
220        models: impl IntoIterator<Item = impl Into<String>>,
221    ) -> Result<Self, EmptyFallbacks> {
222        let models: Vec<String> = models.into_iter().map(Into::into).collect();
223        if models.is_empty() {
224            return Err(EmptyFallbacks);
225        }
226        Ok(Self(models))
227    }
228
229    /// The fallback models, in order.
230    pub fn models(&self) -> &[String] {
231        &self.0
232    }
233}
234
235/// Whether providers that may store request data are eligible.
236#[non_exhaustive]
237#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
238#[serde(rename_all = "lowercase")]
239pub enum DataCollection {
240    /// Any provider.
241    Allow,
242    /// Only providers that store no request data beyond the request.
243    Deny,
244}
245
246/// A quantization an upstream provider serves a model at.
247#[non_exhaustive]
248#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
249#[serde(rename_all = "lowercase")]
250pub enum Quantization {
251    /// 4-bit integers.
252    Int4,
253    /// 8-bit integers.
254    Int8,
255    /// 16-bit floats.
256    Fp16,
257    /// Brain floats.
258    Bf16,
259    /// 32-bit floats.
260    Fp32,
261    /// 8-bit floats.
262    Fp8,
263    /// Not stated by the provider.
264    Unknown,
265}
266
267/// What providers are ordered by.
268#[non_exhaustive]
269#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
270#[serde(rename_all = "lowercase")]
271pub enum ProviderSortStrategy {
272    /// Cheapest first.
273    Price,
274    /// Highest throughput first.
275    Throughput,
276    /// Lowest latency first.
277    Latency,
278}
279
280/// How a request with fallback models sorts its providers.
281#[non_exhaustive]
282#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
283#[serde(rename_all = "lowercase")]
284pub enum SortPartition {
285    /// Within each model.
286    Model,
287    /// Across every model.
288    None,
289}
290
291/// A sort with a partition.
292#[non_exhaustive]
293#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
294pub struct ProviderSortConfig {
295    /// What providers are ordered by.
296    pub by: ProviderSortStrategy,
297    /// How fallback models are grouped.
298    #[serde(skip_serializing_if = "Option::is_none")]
299    pub partition: Option<SortPartition>,
300}
301
302impl ProviderSortConfig {
303    /// Sort by `by`.
304    pub fn new(by: ProviderSortStrategy) -> Self {
305        Self {
306            by,
307            partition: None,
308        }
309    }
310
311    /// Group fallback models by `partition`.
312    pub fn partition(mut self, partition: SortPartition) -> Self {
313        self.partition = Some(partition);
314        self
315    }
316}
317
318/// A provider sort: a strategy, or a strategy with a partition.
319#[non_exhaustive]
320#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
321#[serde(untagged)]
322pub enum ProviderSort {
323    /// A strategy alone.
324    Simple(ProviderSortStrategy),
325    /// A strategy and a partition.
326    Complex(ProviderSortConfig),
327}
328
329impl From<ProviderSortStrategy> for ProviderSort {
330    fn from(strategy: ProviderSortStrategy) -> Self {
331        Self::Simple(strategy)
332    }
333}
334
335impl From<ProviderSortConfig> for ProviderSort {
336    fn from(config: ProviderSortConfig) -> Self {
337        Self::Complex(config)
338    }
339}
340
341/// A throughput floor in tokens per second, alone or per percentile.
342/// Providers below it are tried later, not excluded.
343#[non_exhaustive]
344#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
345#[serde(untagged)]
346pub enum ThroughputThreshold {
347    /// One floor.
348    Simple(#[serde(deserialize_with = "crate::json_utils::floats")] f64),
349    /// A floor per percentile.
350    Percentile(PercentileThresholds),
351}
352
353/// A latency ceiling in seconds, alone or per percentile. Providers above
354/// it are tried later, not excluded.
355#[non_exhaustive]
356#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
357#[serde(untagged)]
358pub enum LatencyThreshold {
359    /// One ceiling.
360    Simple(#[serde(deserialize_with = "crate::json_utils::floats")] f64),
361    /// A ceiling per percentile.
362    Percentile(PercentileThresholds),
363}
364
365/// A threshold per percentile.
366#[non_exhaustive]
367#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
368#[serde(from = "PercentilesRead")]
369pub struct PercentileThresholds {
370    /// The median.
371    #[serde(skip_serializing_if = "Option::is_none")]
372    pub p50: Option<f64>,
373    /// The 75th percentile.
374    #[serde(skip_serializing_if = "Option::is_none")]
375    pub p75: Option<f64>,
376    /// The 90th percentile.
377    #[serde(skip_serializing_if = "Option::is_none")]
378    pub p90: Option<f64>,
379    /// The 99th percentile.
380    #[serde(skip_serializing_if = "Option::is_none")]
381    pub p99: Option<f64>,
382}
383
384/// [`PercentileThresholds`] as read: each percentile goes through `floats`
385/// in a plain `Option`, so it reads in the thresholds' untagged buffer and
386/// keeps serde's rules for an absent, repeated or unknown key.
387#[derive(Deserialize)]
388struct PercentilesRead {
389    p50: Option<Percentile>,
390    p75: Option<Percentile>,
391    p90: Option<Percentile>,
392    p99: Option<Percentile>,
393}
394
395/// One percentile's threshold.
396#[derive(Deserialize)]
397struct Percentile(#[serde(deserialize_with = "crate::json_utils::floats")] f64);
398
399impl From<PercentilesRead> for PercentileThresholds {
400    fn from(read: PercentilesRead) -> Self {
401        let value = |percentile: Option<Percentile>| percentile.map(|Percentile(value)| value);
402        Self {
403            p50: value(read.p50),
404            p75: value(read.p75),
405            p90: value(read.p90),
406            p99: value(read.p99),
407        }
408    }
409}
410
411impl PercentileThresholds {
412    /// No threshold.
413    pub fn new() -> Self {
414        Self::default()
415    }
416
417    /// Set the median threshold.
418    pub fn p50(mut self, value: f64) -> Self {
419        self.p50 = Some(value);
420        self
421    }
422
423    /// Set the 75th-percentile threshold.
424    pub fn p75(mut self, value: f64) -> Self {
425        self.p75 = Some(value);
426        self
427    }
428
429    /// Set the 90th-percentile threshold.
430    pub fn p90(mut self, value: f64) -> Self {
431        self.p90 = Some(value);
432        self
433    }
434
435    /// Set the 99th-percentile threshold.
436    pub fn p99(mut self, value: f64) -> Self {
437        self.p99 = Some(value);
438        self
439    }
440}
441
442/// Price ceilings, in USD per million tokens or per item. A request no
443/// eligible provider can serve under them fails.
444#[non_exhaustive]
445#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
446#[serde(deny_unknown_fields)]
447pub struct MaxPrice {
448    /// Per million prompt tokens.
449    #[serde(skip_serializing_if = "Option::is_none")]
450    pub prompt: Option<f64>,
451    /// Per million completion tokens.
452    #[serde(skip_serializing_if = "Option::is_none")]
453    pub completion: Option<f64>,
454    /// Per request.
455    #[serde(skip_serializing_if = "Option::is_none")]
456    pub request: Option<f64>,
457    /// Per image.
458    #[serde(skip_serializing_if = "Option::is_none")]
459    pub image: Option<f64>,
460}
461
462impl MaxPrice {
463    /// No ceiling.
464    pub fn new() -> Self {
465        Self::default()
466    }
467
468    /// Cap the prompt price.
469    pub fn prompt(mut self, price: f64) -> Self {
470        self.prompt = Some(price);
471        self
472    }
473
474    /// Cap the completion price.
475    pub fn completion(mut self, price: f64) -> Self {
476        self.completion = Some(price);
477        self
478    }
479
480    /// Cap the price per request.
481    pub fn request(mut self, price: f64) -> Self {
482        self.request = Some(price);
483        self
484    }
485
486    /// Cap the price per image.
487    pub fn image(mut self, price: f64) -> Self {
488        self.image = Some(price);
489        self
490    }
491}
492
493/// Which upstream providers may serve a request and in what order
494/// (<https://openrouter.ai/docs/guides/routing/provider-selection>). Unset
495/// fields keep OpenRouter's defaults. Slugs and limits are sent as given.
496#[non_exhaustive]
497#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
498#[serde(deny_unknown_fields)]
499pub struct ProviderPreferences {
500    /// Provider slugs tried first, in order.
501    #[serde(skip_serializing_if = "Option::is_none")]
502    pub order: Option<Vec<String>>,
503    /// The only eligible provider slugs.
504    #[serde(skip_serializing_if = "Option::is_none")]
505    pub only: Option<Vec<String>>,
506    /// Provider slugs never used.
507    #[serde(skip_serializing_if = "Option::is_none")]
508    pub ignore: Option<Vec<String>>,
509    /// Whether providers outside `order` may serve the request.
510    #[serde(skip_serializing_if = "Option::is_none")]
511    pub allow_fallbacks: Option<bool>,
512    /// Whether only providers taking every request parameter are eligible.
513    #[serde(skip_serializing_if = "Option::is_none")]
514    pub require_parameters: Option<bool>,
515    /// Whether providers that store request data are eligible.
516    #[serde(skip_serializing_if = "Option::is_none")]
517    pub data_collection: Option<DataCollection>,
518    /// Whether only zero-data-retention endpoints are eligible.
519    #[serde(skip_serializing_if = "Option::is_none")]
520    pub zdr: Option<bool>,
521    /// The order providers are tried in, in place of load balancing.
522    #[serde(skip_serializing_if = "Option::is_none")]
523    pub sort: Option<ProviderSort>,
524    /// The throughput below which a provider is tried later.
525    #[serde(skip_serializing_if = "Option::is_none")]
526    pub preferred_min_throughput: Option<ThroughputThreshold>,
527    /// The latency above which a provider is tried later.
528    #[serde(skip_serializing_if = "Option::is_none")]
529    pub preferred_max_latency: Option<LatencyThreshold>,
530    /// The price ceilings.
531    #[serde(skip_serializing_if = "Option::is_none")]
532    pub max_price: Option<MaxPrice>,
533    /// The quantizations a provider may serve the model at.
534    #[serde(skip_serializing_if = "Option::is_none")]
535    pub quantizations: Option<Vec<Quantization>>,
536}
537
538fn strings(items: impl IntoIterator<Item = impl Into<String>>) -> Option<Vec<String>> {
539    Some(items.into_iter().map(Into::into).collect())
540}
541
542impl ProviderPreferences {
543    /// No preference.
544    pub fn new() -> Self {
545        Self::default()
546    }
547
548    /// Try `providers` first, in order.
549    pub fn order(mut self, providers: impl IntoIterator<Item = impl Into<String>>) -> Self {
550        self.order = strings(providers);
551        self
552    }
553
554    /// Make only `providers` eligible.
555    pub fn only(mut self, providers: impl IntoIterator<Item = impl Into<String>>) -> Self {
556        self.only = strings(providers);
557        self
558    }
559
560    /// Never use `providers`.
561    pub fn ignore(mut self, providers: impl IntoIterator<Item = impl Into<String>>) -> Self {
562        self.ignore = strings(providers);
563        self
564    }
565
566    /// Whether providers outside `order` may serve the request.
567    pub fn allow_fallbacks(mut self, allow: bool) -> Self {
568        self.allow_fallbacks = Some(allow);
569        self
570    }
571
572    /// Whether only providers taking every request parameter are eligible.
573    pub fn require_parameters(mut self, require: bool) -> Self {
574        self.require_parameters = Some(require);
575        self
576    }
577
578    /// Set the data collection policy.
579    pub fn data_collection(mut self, policy: DataCollection) -> Self {
580        self.data_collection = Some(policy);
581        self
582    }
583
584    /// Whether only zero-data-retention endpoints are eligible.
585    pub fn zdr(mut self, enable: bool) -> Self {
586        self.zdr = Some(enable);
587        self
588    }
589
590    /// Try providers in the order `sort` gives.
591    pub fn sort(mut self, sort: impl Into<ProviderSort>) -> Self {
592        self.sort = Some(sort.into());
593        self
594    }
595
596    /// Try providers below `threshold` later.
597    pub fn preferred_min_throughput(mut self, threshold: ThroughputThreshold) -> Self {
598        self.preferred_min_throughput = Some(threshold);
599        self
600    }
601
602    /// Try providers above `threshold` later.
603    pub fn preferred_max_latency(mut self, threshold: LatencyThreshold) -> Self {
604        self.preferred_max_latency = Some(threshold);
605        self
606    }
607
608    /// Fail the request when no provider is under `price`.
609    pub fn max_price(mut self, price: MaxPrice) -> Self {
610        self.max_price = Some(price);
611        self
612    }
613
614    /// Make only providers serving one of `quantizations` eligible.
615    pub fn quantizations(mut self, quantizations: impl IntoIterator<Item = Quantization>) -> Self {
616        self.quantizations = Some(quantizations.into_iter().collect());
617        self
618    }
619
620    /// Try the cheapest provider first.
621    pub fn cheapest(self) -> Self {
622        self.sort(ProviderSortStrategy::Price)
623    }
624}
625
626/// OpenRouter's reply fields. Each is `None` when the reply lacks it.
627#[non_exhaustive]
628#[derive(Clone, Debug, Default, PartialEq)]
629pub struct OpenRouterExtras {
630    /// The upstream provider that served the request. Chat; Responses when
631    /// sent.
632    pub provider: Option<String>,
633    /// The upstream provider's own finish reason. Chat only.
634    pub native_finish_reason: Option<String>,
635    /// The service tier that served the request. Both routes.
636    pub service_tier: Option<String>,
637    /// The upstream backend's fingerprint. Chat only.
638    pub system_fingerprint: Option<String>,
639    /// The request's cost in credits. Both routes.
640    pub cost: Option<f64>,
641    /// The cost broken down by upstream charge. Both routes, keyed as each
642    /// route spells them.
643    pub cost_details: Option<Map<String, Value>>,
644    /// Whether the request ran on the caller's own provider key. Both
645    /// routes.
646    pub is_byok: Option<bool>,
647    /// Prompt token details: `usage.prompt_tokens_details` on Chat,
648    /// `usage.input_tokens_details` on Responses.
649    pub prompt_tokens_details: Option<Value>,
650    /// Server tool usage, such as web searches. Chat only.
651    pub server_tool_use_details: Option<Value>,
652    /// OpenRouter's routing metadata. Chat only.
653    pub openrouter_metadata: Option<Value>,
654    /// The message's annotations, such as URL citations. Chat only.
655    pub annotations: Option<Vec<Value>>,
656}
657
658impl ReplyExtras for OpenRouterExtras {
659    fn from_reply(api: &Api, raw: &Value) -> Result<Self, serde_json::Error> {
660        if api.as_str() == "openai.responses" {
661            return Ok(Self {
662                provider: reply_field(raw, "/provider")?,
663                service_tier: reply_field(raw, "/service_tier")?,
664                cost: reply_field(raw, "/usage/cost")?,
665                cost_details: reply_field(raw, "/usage/cost_details")?,
666                is_byok: reply_field(raw, "/usage/is_byok")?,
667                prompt_tokens_details: reply_field(raw, "/usage/input_tokens_details")?,
668                ..Self::default()
669            });
670        }
671        Ok(Self {
672            provider: reply_field(raw, "/provider")?,
673            native_finish_reason: reply_field(raw, "/choices/0/native_finish_reason")?,
674            service_tier: reply_field(raw, "/service_tier")?,
675            system_fingerprint: reply_field(raw, "/system_fingerprint")?,
676            cost: reply_field(raw, "/usage/cost")?,
677            cost_details: reply_field(raw, "/usage/cost_details")?,
678            is_byok: reply_field(raw, "/usage/is_byok")?,
679            prompt_tokens_details: reply_field(raw, "/usage/prompt_tokens_details")?,
680            server_tool_use_details: reply_field(raw, "/usage/server_tool_use_details")?,
681            openrouter_metadata: reply_field(raw, "/openrouter_metadata")?,
682            annotations: reply_field(raw, "/choices/0/message/annotations")?,
683        })
684    }
685}
686
687#[cfg(test)]
688mod tests;