Skip to main content

jev/
config.rs

1//! `Config`, `Surface`, `RetryConfig`, and `Thresholds`.
2
3use std::{collections::HashMap, str::FromStr, time::Duration};
4
5use serde::{Deserialize, Deserializer, Serialize, de::Error as _};
6
7use crate::{
8    error::Error,
9    model::{DEFAULT_MODEL, Model},
10    provider::Provider,
11};
12
13/// Default per-request timeout.
14pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
15/// Default maximum retry attempts, including the first.
16pub const DEFAULT_MAX_ATTEMPTS: u32 = 3;
17/// Default initial backoff before the first retry.
18pub const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_millis(200);
19/// Default backoff cap.
20pub const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(2);
21
22/// Which HTTP surface a [`crate::Client`] talks to.
23///
24/// Both surfaces answer the same questions with the same semantics; see the
25/// crate-level docs for the field differences. [`Surface::Decisions`] is the
26/// default because it is the one documented for non-official-SDK clients and
27/// supports `session_id` / `trace` for cross-service observability.
28///
29/// # Examples
30///
31/// ```
32/// use jev::Surface;
33///
34/// assert_eq!(Surface::default(), Surface::Decisions);
35/// assert_eq!(Surface::Decisions.path(), "/api/alpha/decisions");
36/// assert_eq!(Surface::SystemOne.path(), "/api/v1/systemone");
37/// ```
38#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
39#[serde(rename_all = "camelCase")]
40pub enum Surface {
41    /// `POST /api/alpha/decisions`. Alpha. Adds `provider`, `session_id`, `trace`, `user`.
42    #[default]
43    Decisions,
44    /// `POST /api/v1/systemone`. Stable `v1` path. Accepts bare model IDs.
45    SystemOne,
46}
47
48impl Surface {
49    /// The HTTP path this surface is served at.
50    #[must_use]
51    pub fn path(self) -> &'static str {
52        match self {
53            Surface::Decisions => "/api/alpha/decisions",
54            Surface::SystemOne => "/api/v1/systemone",
55        }
56    }
57}
58
59/// Bounded retry configuration honouring `Retry-After`.
60///
61/// The endpoint has no idempotency key, so a retry can double-bill a request that
62/// the server actually processed but whose response was lost to a transport error.
63/// Set `max_attempts: 1` to disable retry entirely when that risk is unacceptable.
64///
65/// # Examples
66///
67/// ```
68/// use jev::RetryConfig;
69/// use std::time::Duration;
70///
71/// let no_retry = RetryConfig::disabled();
72/// assert_eq!(no_retry.max_attempts, 1);
73///
74/// let custom = RetryConfig::default().with_max_attempts(5).with_initial_backoff(Duration::from_millis(50));
75/// assert_eq!(custom.max_attempts, 5);
76/// ```
77#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
78#[serde(rename_all = "camelCase", default)]
79pub struct RetryConfig {
80    /// Maximum number of attempts, including the first. `1` disables retry.
81    pub max_attempts: u32,
82    /// Backoff before the first retry.
83    #[serde(with = "duration_millis", rename = "initialBackoffMs")]
84    pub initial_backoff: Duration,
85    /// Backoff cap; `Retry-After` is clamped to this.
86    #[serde(with = "duration_millis", rename = "maxBackoffMs")]
87    pub max_backoff: Duration,
88}
89
90impl Default for RetryConfig {
91    fn default() -> Self {
92        RetryConfig {
93            max_attempts: DEFAULT_MAX_ATTEMPTS,
94            initial_backoff: DEFAULT_INITIAL_BACKOFF,
95            max_backoff: DEFAULT_MAX_BACKOFF,
96        }
97    }
98}
99
100impl RetryConfig {
101    /// A configuration that never retries.
102    #[must_use]
103    pub fn disabled() -> Self {
104        RetryConfig {
105            max_attempts: 1,
106            ..Self::default()
107        }
108    }
109
110    /// Sets the maximum attempt count.
111    #[must_use]
112    pub fn with_max_attempts(mut self, max_attempts: u32) -> Self {
113        self.max_attempts = max_attempts;
114        self
115    }
116
117    /// Sets the initial backoff.
118    #[must_use]
119    pub fn with_initial_backoff(mut self, backoff: Duration) -> Self {
120        self.initial_backoff = backoff;
121        self
122    }
123
124    /// Sets the backoff cap.
125    #[must_use]
126    pub fn with_max_backoff(mut self, backoff: Duration) -> Self {
127        self.max_backoff = backoff;
128        self
129    }
130}
131
132/// `serde` helper for `Duration <-> milliseconds` fields.
133mod duration_millis {
134    use std::time::Duration;
135
136    use serde::{Deserialize, Deserializer, Serializer};
137
138    pub(super) fn serialize<S: Serializer>(d: &Duration, s: S) -> Result<S::Ok, S::Error> {
139        s.serialize_u64(u64::try_from(d.as_millis()).unwrap_or(u64::MAX))
140    }
141
142    pub(super) fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Duration, D::Error> {
143        let ms = u64::deserialize(d)?;
144        Ok(Duration::from_millis(ms))
145    }
146}
147
148/// Named, runtime-tunable probability thresholds.
149///
150/// The SDK never picks a threshold itself; gates like [`crate::Noul::is_yes`] and
151/// [`crate::Choice::confident`] take a threshold as an explicit argument. `Thresholds`
152/// exists so an application can load those numbers from configuration instead of
153/// hard-coding them, and swap them without a redeploy (wrap `Config` in `ArcSwap`;
154/// the SDK imposes no reload mechanism of its own).
155///
156/// Every value is validated to be finite and within `0.0..=1.0` when the map is
157/// built or deserialized.
158///
159/// # Examples
160///
161/// ```
162/// use jev::Thresholds;
163///
164/// let mut thresholds = Thresholds::new();
165/// thresholds.insert("autoRouteConfidence", 0.7).unwrap();
166/// assert_eq!(thresholds.get("autoRouteConfidence"), Some(0.7));
167/// assert!(thresholds.require("missing").is_err());
168/// ```
169#[derive(Debug, Clone, Default, PartialEq, Serialize)]
170#[serde(transparent)]
171pub struct Thresholds(HashMap<String, f64>);
172
173impl Thresholds {
174    /// An empty threshold set.
175    #[must_use]
176    pub fn new() -> Self {
177        Thresholds(HashMap::new())
178    }
179
180    /// Inserts or replaces a named threshold.
181    ///
182    /// # Errors
183    ///
184    /// Returns [`Error::Invalid`] if `value` is not finite or not within `0.0..=1.0`.
185    pub fn insert(&mut self, name: impl Into<String>, value: f64) -> Result<(), Error> {
186        validate_threshold(value)?;
187        self.0.insert(name.into(), value);
188        Ok(())
189    }
190
191    /// Reads a named threshold, if present.
192    #[must_use]
193    pub fn get(&self, name: &str) -> Option<f64> {
194        self.0.get(name).copied()
195    }
196
197    /// Reads a named threshold, or a named [`Error::Invalid`] if absent.
198    ///
199    /// # Errors
200    ///
201    /// Returns [`Error::Invalid`] when `name` has no configured value.
202    pub fn require(&self, name: &str) -> Result<f64, Error> {
203        self.get(name).ok_or_else(|| Error::Invalid {
204            field: format!("thresholds.{name}"),
205            reason: "no threshold configured for this name".to_string(),
206        })
207    }
208}
209
210/// Validates a threshold is finite and within `0.0..=1.0`.
211fn validate_threshold(value: f64) -> Result<(), Error> {
212    if !value.is_finite() || !(0.0..=1.0).contains(&value) {
213        return Err(Error::Invalid {
214            field: "threshold".to_string(),
215            reason: format!("must be finite and within 0.0..=1.0, got {value}"),
216        });
217    }
218    Ok(())
219}
220
221impl<'de> Deserialize<'de> for Thresholds {
222    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
223    where
224        D: Deserializer<'de>,
225    {
226        let map = HashMap::<String, f64>::deserialize(deserializer)?;
227        let mut thresholds = Thresholds::new();
228        for (name, value) in map {
229            thresholds.insert(name, value).map_err(D::Error::custom)?;
230        }
231        Ok(thresholds)
232    }
233}
234
235/// Deserializable client configuration, for the config-file path.
236///
237/// Nests under an application's YAML with `#[serde(rename_all = "camelCase", deny_unknown_fields)]`
238/// so a typo in a threshold name or config key is rejected at load time instead of
239/// silently ignored:
240///
241/// ```yaml
242/// jev:
243///   model: typesafe/jev-1.13
244///   surface: decisions
245///   timeoutMs: 10000
246///   retry:
247///     maxAttempts: 3
248///     initialBackoffMs: 200
249///     maxBackoffMs: 2000
250///   thresholds:
251///     autoRouteConfidence: 0.7
252///     isBugYes: 0.9
253/// ```
254///
255/// # Examples
256///
257/// ```
258/// let yaml = r#"
259/// model: typesafe/jev-1.13
260/// surface: decisions
261/// timeoutMs: 5000
262/// thresholds:
263///   isBugYes: 0.9
264/// "#;
265/// let config: jev::Config = serde_norway::from_str(yaml).unwrap();
266/// assert_eq!(config.surface, jev::Surface::Decisions);
267/// assert_eq!(config.thresholds.get("isBugYes"), Some(0.9));
268/// ```
269#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
270#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
271pub struct Config {
272    /// The hosted provider. Defaults to `OpenRouter`; `TypeSafe` always uses System One.
273    pub provider: Provider,
274    /// The model to request. Defaults to [`crate::DEFAULT_MODEL`].
275    #[serde(with = "model_as_string")]
276    pub model: Model,
277    /// The `OpenRouter` HTTP surface to call. `TypeSafe` always uses System One.
278    pub surface: Surface,
279    /// Override for the API base URL (scheme + host), mainly for tests.
280    #[serde(skip_serializing_if = "Option::is_none")]
281    pub api_base: Option<url::Url>,
282    /// Per-request timeout.
283    #[serde(with = "duration_millis", rename = "timeoutMs")]
284    pub timeout: Duration,
285    /// Retry policy.
286    pub retry: RetryConfig,
287    /// Named probability thresholds.
288    pub thresholds: Thresholds,
289    /// Whether to run the cheap pre-flight context-size estimate.
290    pub context_check: bool,
291    /// Default session identifier applied to every request unless overridden by
292    /// `RequestOptions::with_session_id` (Decisions surface only).
293    #[serde(skip_serializing_if = "Option::is_none")]
294    pub default_session_id: Option<String>,
295    /// Default user identifier applied to every request unless overridden by
296    /// `RequestOptions::with_user` (Decisions surface only).
297    #[serde(skip_serializing_if = "Option::is_none")]
298    pub default_user: Option<String>,
299}
300
301impl Default for Config {
302    fn default() -> Self {
303        Config {
304            provider: Provider::default(),
305            model: DEFAULT_MODEL,
306            surface: Surface::default(),
307            api_base: None,
308            timeout: DEFAULT_TIMEOUT,
309            retry: RetryConfig::default(),
310            thresholds: Thresholds::default(),
311            context_check: true,
312            default_session_id: None,
313            default_user: None,
314        }
315    }
316}
317
318/// `serde` helper for `Model <-> String` via [`FromStr`] / [`std::fmt::Display`].
319mod model_as_string {
320    use serde::{Deserialize, Deserializer, Serializer};
321
322    use super::{FromStr, Model};
323
324    pub(super) fn serialize<S: Serializer>(m: &Model, s: S) -> Result<S::Ok, S::Error> {
325        s.serialize_str(&m.to_string())
326    }
327
328    pub(super) fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Model, D::Error> {
329        let s = String::deserialize(d)?;
330        Model::from_str(&s).map_err(serde::de::Error::custom)
331    }
332}
333
334#[cfg(test)]
335mod tests {
336    use super::*;
337
338    #[test]
339    fn test_should_default_config_to_pinned_model_and_decisions_surface() {
340        let config = Config::default();
341        assert_eq!(config.model, DEFAULT_MODEL);
342        assert_eq!(config.provider, Provider::OpenRouter);
343        assert_eq!(config.surface, Surface::Decisions);
344        assert!(config.context_check);
345    }
346
347    #[test]
348    fn test_should_deserialize_config_from_yaml() {
349        let yaml = r#"
350model: typesafe/jev-1.13
351surface: systemOne
352timeoutMs: 5000
353retry:
354  maxAttempts: 5
355  initialBackoffMs: 100
356  maxBackoffMs: 1000
357thresholds:
358  isBugYes: 0.9
359contextCheck: false
360"#;
361        let config: Config = serde_norway::from_str(yaml).unwrap();
362        assert_eq!(config.model, Model::Jev113);
363        assert_eq!(config.surface, Surface::SystemOne);
364        assert_eq!(config.timeout, Duration::from_millis(5000));
365        assert_eq!(config.retry.max_attempts, 5);
366        assert_eq!(config.thresholds.get("isBugYes"), Some(0.9));
367        assert!(!config.context_check);
368    }
369
370    #[test]
371    fn test_should_reject_unknown_config_field() {
372        let yaml = "model: jev-1.13\nbogusField: 1\n";
373        assert!(serde_norway::from_str::<Config>(yaml).is_err());
374    }
375
376    #[test]
377    fn test_should_reject_out_of_range_threshold_in_config() {
378        let yaml = "thresholds:\n  bad: 1.5\n";
379        assert!(serde_norway::from_str::<Config>(yaml).is_err());
380    }
381
382    #[test]
383    fn test_should_reject_out_of_range_threshold_on_insert() {
384        let mut thresholds = Thresholds::new();
385        assert!(thresholds.insert("bad", 1.5).is_err());
386        assert!(thresholds.insert("bad", f64::NAN).is_err());
387        assert!(thresholds.insert("good", 0.5).is_ok());
388    }
389
390    #[test]
391    fn test_should_require_return_error_for_missing_threshold() {
392        let thresholds = Thresholds::new();
393        assert!(matches!(
394            thresholds.require("missing"),
395            Err(Error::Invalid { .. })
396        ));
397    }
398
399    #[test]
400    fn test_should_build_retry_config_via_builder_methods() {
401        let retry = RetryConfig::default()
402            .with_max_attempts(5)
403            .with_initial_backoff(Duration::from_millis(50))
404            .with_max_backoff(Duration::from_secs(1));
405        assert_eq!(retry.max_attempts, 5);
406        assert_eq!(retry.initial_backoff, Duration::from_millis(50));
407        assert_eq!(retry.max_backoff, Duration::from_secs(1));
408    }
409
410    #[test]
411    fn test_should_disable_retry_with_one_attempt() {
412        assert_eq!(RetryConfig::disabled().max_attempts, 1);
413    }
414
415    #[test]
416    fn test_surface_path_matches_documented_endpoints() {
417        assert_eq!(Surface::Decisions.path(), "/api/alpha/decisions");
418        assert_eq!(Surface::SystemOne.path(), "/api/v1/systemone");
419    }
420}