Skip to main content

typesafe/
response.rs

1//! Answers and response metadata.
2//!
3//! The answer types serialize to the JSON the API sends, so a response can be stored and read
4//! back: an [`Answer`] carries its wire `type` tag, and a [`SystemOneResponse`] serializes to its
5//! `{"model", "answers", "usage"}` body.
6
7use std::collections::BTreeMap;
8use std::fmt;
9use std::str::FromStr;
10
11use http::StatusCode;
12use http::header::HeaderMap;
13use indexmap::IndexMap;
14use serde::de::{self, DeserializeOwned, Deserializer};
15use serde::ser::{SerializeMap, SerializeStruct, Serializer};
16use serde::{Deserialize, Serialize};
17use serde_json::Value;
18use serde_json::value::RawValue;
19
20use crate::constants::REQUEST_ID_HEADER;
21
22/// A yes/no answer.
23#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
24#[non_exhaustive]
25pub struct NoulAnswer {
26    /// Probability of "yes", from 0 to 1.
27    pub noul: f64,
28}
29
30impl NoulAnswer {
31    /// `noul >= threshold`.
32    pub fn is_yes(&self, threshold: f64) -> bool {
33        self.noul >= threshold
34    }
35}
36
37/// A selected option with its distribution.
38#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
39#[non_exhaustive]
40pub struct ChoiceAnswer {
41    /// The highest-probability option.
42    pub choice: String,
43    /// Every option mapped to its probability, in server order.
44    pub probabilities: IndexMap<String, f64>,
45    /// Certainty derived from the distribution, 0 to 1.
46    pub confidence: f64,
47}
48
49impl ChoiceAnswer {
50    /// Parse the selected label into your own type (e.g. an enum implementing `FromStr`).
51    ///
52    /// # Errors
53    ///
54    /// Whatever `T::from_str` returns for the label.
55    pub fn parse<T: FromStr>(&self) -> Result<T, T::Err> {
56        self.choice.parse()
57    }
58
59    /// Probability of a given label.
60    pub fn probability(&self, label: &str) -> Option<f64> {
61        self.probabilities.get(label).copied()
62    }
63
64    /// Labels ordered by descending probability.
65    pub fn ranked(&self) -> Vec<(&str, f64)> {
66        let mut v: Vec<_> = self
67            .probabilities
68            .iter()
69            .map(|(k, p)| (k.as_str(), *p))
70            .collect();
71        v.sort_by(|a, b| b.1.total_cmp(&a.1));
72        v
73    }
74}
75
76/// An expected score with its rubric and distribution.
77#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
78#[non_exhaustive]
79pub struct ScoreAnswer {
80    /// Probability-weighted level; may fall between levels.
81    pub score: f64,
82    /// Certainty derived from the distribution, 0 to 1.
83    pub confidence: f64,
84    /// Level index → the description you supplied.
85    pub legend: BTreeMap<u32, Value>,
86    /// Level index → probability.
87    pub probabilities: BTreeMap<u32, f64>,
88}
89
90impl ScoreAnswer {
91    /// The single most likely level (argmax of `probabilities`), as opposed to the weighted `score`.
92    pub fn most_likely_level(&self) -> Option<u32> {
93        self.probabilities
94            .iter()
95            .max_by(|a, b| a.1.total_cmp(b.1))
96            .map(|(level, _)| *level)
97    }
98
99    /// `score` rounded to the nearest level.
100    pub fn rounded_level(&self) -> u32 {
101        self.score.round().max(0.0) as u32
102    }
103}
104
105/// Edges of a box, as fractions of the image's height and width from its top-left corner:
106/// `left < right` and `top < bottom`.
107#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
108#[non_exhaustive]
109pub struct BoundingBox {
110    /// Distance of the top edge from the top of the image, 0 to 1.
111    pub top: f64,
112    /// Distance of the bottom edge from the top of the image, 0 to 1.
113    pub bottom: f64,
114    /// Distance of the left edge from the left of the image, 0 to 1.
115    pub left: f64,
116    /// Distance of the right edge from the left of the image, 0 to 1.
117    pub right: f64,
118}
119
120impl BoundingBox {
121    /// The box's width, as a fraction of the image's.
122    pub fn width(&self) -> f64 {
123        self.right - self.left
124    }
125
126    /// The box's height, as a fraction of the image's.
127    pub fn height(&self) -> f64 {
128        self.bottom - self.top
129    }
130
131    /// The box in pixels of a `width` × `height` image, as `(left, top, right, bottom)`.
132    pub fn to_pixels(&self, width: u32, height: u32) -> (u32, u32, u32, u32) {
133        let px = |f: f64, size: u32| (f.clamp(0.0, 1.0) * f64::from(size)).round() as u32;
134        (
135            px(self.left, width),
136            px(self.top, height),
137            px(self.right, width),
138            px(self.bottom, height),
139        )
140    }
141}
142
143/// Where a [`BoxQuestion`](crate::BoxQuestion)'s thing is in the image. Experimental, Jev 1.14
144/// and later.
145#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
146#[non_exhaustive]
147pub struct BoxAnswer {
148    /// The box (`box` on the wire).
149    #[serde(rename = "box")]
150    pub bounds: BoundingBox,
151    /// Certainty of the box, 0 to 1.
152    pub confidence: f64,
153}
154
155/// An answer to one question.
156#[derive(Debug, Clone, PartialEq)]
157#[non_exhaustive]
158pub enum Answer {
159    /// See [`NoulAnswer`].
160    Noul(NoulAnswer),
161    /// See [`ChoiceAnswer`].
162    Choice(ChoiceAnswer),
163    /// See [`ScoreAnswer`].
164    Score(ScoreAnswer),
165    /// See [`BoxAnswer`].
166    Box(BoxAnswer),
167}
168
169/// The type of an [`Answer`]; `Display` gives its wire `type` tag.
170#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
171#[non_exhaustive]
172pub enum AnswerKind {
173    /// A [`NoulAnswer`], `"noul"`.
174    Noul,
175    /// A [`ChoiceAnswer`], `"choice"`.
176    Choice,
177    /// A [`ScoreAnswer`], `"score"`.
178    Score,
179    /// A [`BoxAnswer`], `"box"`.
180    Box,
181}
182
183impl AnswerKind {
184    /// The wire `type` tag: `"noul"`, `"choice"`, `"score"` or `"box"`.
185    pub const fn as_str(self) -> &'static str {
186        match self {
187            AnswerKind::Noul => "noul",
188            AnswerKind::Choice => "choice",
189            AnswerKind::Score => "score",
190            AnswerKind::Box => "box",
191        }
192    }
193}
194
195impl fmt::Display for AnswerKind {
196    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
197        f.write_str(self.as_str())
198    }
199}
200
201impl Answer {
202    /// The answer's type.
203    pub fn kind(&self) -> AnswerKind {
204        match self {
205            Answer::Noul(_) => AnswerKind::Noul,
206            Answer::Choice(_) => AnswerKind::Choice,
207            Answer::Score(_) => AnswerKind::Score,
208            Answer::Box(_) => AnswerKind::Box,
209        }
210    }
211
212    /// Confidence, for answer types that report it.
213    pub fn confidence(&self) -> Option<f64> {
214        match self {
215            Answer::Noul(_) => None,
216            Answer::Choice(a) => Some(a.confidence),
217            Answer::Score(a) => Some(a.confidence),
218            Answer::Box(a) => Some(a.confidence),
219        }
220    }
221}
222
223/// Serialized with its wire `type` tag: `{"type": "noul", "noul": 0.97}`.
224impl Serialize for Answer {
225    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
226        let mut m = s.serialize_map(None)?;
227        m.serialize_entry("type", self.kind().as_str())?;
228        match self {
229            Answer::Noul(a) => m.serialize_entry("noul", &a.noul)?,
230            Answer::Choice(a) => {
231                m.serialize_entry("choice", &a.choice)?;
232                m.serialize_entry("probabilities", &a.probabilities)?;
233                m.serialize_entry("confidence", &a.confidence)?;
234            }
235            Answer::Score(a) => {
236                m.serialize_entry("score", &a.score)?;
237                m.serialize_entry("legend", &a.legend)?;
238                m.serialize_entry("probabilities", &a.probabilities)?;
239                m.serialize_entry("confidence", &a.confidence)?;
240            }
241            Answer::Box(a) => {
242                m.serialize_entry("box", &a.bounds)?;
243                m.serialize_entry("confidence", &a.confidence)?;
244            }
245        }
246        m.end()
247    }
248}
249
250/// Reads the wire shape, dispatching on `type`; an unknown type is an error.
251impl<'de> Deserialize<'de> for Answer {
252    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
253        // Every field any answer type has, so the body is read once, in order, by any
254        // deserializer. Choice and score probabilities differ in key type, so they are read as
255        // strings and the score's parsed afterwards.
256        #[derive(Deserialize)]
257        struct Wire {
258            #[serde(rename = "type")]
259            kind: String,
260            noul: Option<f64>,
261            choice: Option<String>,
262            score: Option<f64>,
263            confidence: Option<f64>,
264            legend: Option<BTreeMap<u32, Value>>,
265            probabilities: Option<IndexMap<String, f64>>,
266            #[serde(rename = "box")]
267            bounds: Option<BoundingBox>,
268        }
269
270        fn need<T, E: de::Error>(v: Option<T>, field: &'static str) -> Result<T, E> {
271            v.ok_or_else(|| E::missing_field(field))
272        }
273
274        let w = Wire::deserialize(d)?;
275        match w.kind.as_str() {
276            "noul" => Ok(Answer::Noul(NoulAnswer {
277                noul: need(w.noul, "noul")?,
278            })),
279            "choice" => Ok(Answer::Choice(ChoiceAnswer {
280                choice: need(w.choice, "choice")?,
281                probabilities: need(w.probabilities, "probabilities")?,
282                confidence: need(w.confidence, "confidence")?,
283            })),
284            "score" => Ok(Answer::Score(ScoreAnswer {
285                score: need(w.score, "score")?,
286                confidence: need(w.confidence, "confidence")?,
287                legend: need(w.legend, "legend")?,
288                probabilities: need(w.probabilities, "probabilities")?
289                    .into_iter()
290                    .map(|(k, p)| match k.parse() {
291                        Ok(level) => Ok((level, p)),
292                        Err(_) => Err(de::Error::custom(format!("invalid level {k:?}"))),
293                    })
294                    .collect::<Result<_, D::Error>>()?,
295            })),
296            "box" => Ok(Answer::Box(BoxAnswer {
297                bounds: need(w.bounds, "box")?,
298                confidence: need(w.confidence, "confidence")?,
299            })),
300            other => Err(de::Error::unknown_variant(
301                other,
302                &["noul", "choice", "score", "box"],
303            )),
304        }
305    }
306}
307
308/// Token usage. The API reports these when available; absent counts are `None`.
309#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
310#[non_exhaustive]
311pub struct Usage {
312    /// Input tokens, when reported.
313    #[serde(default, skip_serializing_if = "Option::is_none")]
314    pub input_tokens: Option<u64>,
315    /// Output tokens, when reported.
316    #[serde(default, skip_serializing_if = "Option::is_none")]
317    pub output_tokens: Option<u64>,
318}
319
320/// Metadata of the HTTP exchange that produced a response.
321#[derive(Debug, Clone)]
322#[non_exhaustive]
323pub struct ResponseMeta {
324    /// HTTP status.
325    pub status: StatusCode,
326    /// Response headers.
327    pub headers: HeaderMap,
328    /// Number of attempts made, including the successful one; `0` for a replayed response.
329    pub attempts: u32,
330}
331
332impl ResponseMeta {
333    /// The `x-typesafe-request-id` header.
334    pub fn request_id(&self) -> Option<&str> {
335        self.headers
336            .get(REQUEST_ID_HEADER)
337            .and_then(|v| v.to_str().ok())
338    }
339}
340
341/// The result of a System One call.
342#[derive(Debug, Clone)]
343#[non_exhaustive]
344pub struct SystemOneResponse {
345    /// The model that answered.
346    pub model: String,
347    /// Token usage.
348    pub usage: Usage,
349    /// Answers keyed by question name, in server order. Answer types unknown to this SDK version
350    /// are skipped (with a `tracing` warning) and remain visible in [`SystemOneResponse::raw`].
351    pub answers: IndexMap<String, Answer>,
352    /// The full decoded body. Object keys follow `serde_json::Map` ordering (sorted unless your
353    /// build enables serde_json's `preserve_order`); the typed fields above keep server order.
354    pub raw: Value,
355    /// HTTP metadata.
356    pub meta: ResponseMeta,
357}
358
359impl SystemOneResponse {
360    /// The `x-typesafe-request-id` header.
361    pub fn request_id(&self) -> Option<&str> {
362        self.meta.request_id()
363    }
364
365    /// The answer to `name`, if it is a Noul.
366    pub fn noul(&self, name: &str) -> Option<&NoulAnswer> {
367        match self.answers.get(name)? {
368            Answer::Noul(a) => Some(a),
369            _ => None,
370        }
371    }
372
373    /// The answer to `name`, if it is a Choice.
374    pub fn choice(&self, name: &str) -> Option<&ChoiceAnswer> {
375        match self.answers.get(name)? {
376            Answer::Choice(a) => Some(a),
377            _ => None,
378        }
379    }
380
381    /// The answer to `name`, if it is a Score.
382    pub fn score(&self, name: &str) -> Option<&ScoreAnswer> {
383        match self.answers.get(name)? {
384            Answer::Score(a) => Some(a),
385            _ => None,
386        }
387    }
388
389    /// The answer to `name`, if it is a Box.
390    pub fn box_answer(&self, name: &str) -> Option<&BoxAnswer> {
391        match self.answers.get(name)? {
392            Answer::Box(a) => Some(a),
393            _ => None,
394        }
395    }
396
397    /// All Noul answers.
398    pub fn nouls(&self) -> impl Iterator<Item = (&str, &NoulAnswer)> {
399        self.answers.iter().filter_map(|(k, a)| match a {
400            Answer::Noul(n) => Some((k.as_str(), n)),
401            _ => None,
402        })
403    }
404
405    /// All Choice answers.
406    pub fn choices(&self) -> impl Iterator<Item = (&str, &ChoiceAnswer)> {
407        self.answers.iter().filter_map(|(k, a)| match a {
408            Answer::Choice(c) => Some((k.as_str(), c)),
409            _ => None,
410        })
411    }
412
413    /// All Score answers.
414    pub fn scores(&self) -> impl Iterator<Item = (&str, &ScoreAnswer)> {
415        self.answers.iter().filter_map(|(k, a)| match a {
416            Answer::Score(s) => Some((k.as_str(), s)),
417            _ => None,
418        })
419    }
420}
421
422/// Serialized as the body it was decoded from: `{"model", "answers", "usage"}`, answers in server
423/// order. HTTP metadata is left out, as are answers of types this SDK version does not know (see
424/// `raw` for those).
425impl Serialize for SystemOneResponse {
426    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
427        let mut st = s.serialize_struct("SystemOneResponse", 3)?;
428        st.serialize_field("model", &self.model)?;
429        st.serialize_field("answers", &self.answers)?;
430        st.serialize_field("usage", &self.usage)?;
431        st.end()
432    }
433}
434
435/// One available model.
436#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
437#[non_exhaustive]
438pub struct ModelMetadata {
439    /// Model name, e.g. `jev-latest`.
440    pub name: String,
441    /// Description.
442    pub description: String,
443    /// Release date as reported by the API.
444    pub release_date: String,
445}
446
447/// Serialized as the body it was decoded from: `{"models": [...]}`, without HTTP metadata.
448impl Serialize for ListModelsResponse {
449    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
450        let mut st = s.serialize_struct("ListModelsResponse", 1)?;
451        st.serialize_field("models", &self.models)?;
452        st.end()
453    }
454}
455
456/// The models available to the account.
457#[derive(Debug, Clone)]
458#[non_exhaustive]
459pub struct ListModelsResponse {
460    /// Available models.
461    pub models: Vec<ModelMetadata>,
462    /// The full decoded body.
463    pub raw: Value,
464    /// HTTP metadata.
465    pub meta: ResponseMeta,
466}
467
468// ---- decoding ------------------------------------------------------------------------------
469
470/// A decode failure with a dotted path to the offending field.
471pub(crate) struct DecodeFailure {
472    pub path: String,
473    pub detail: String,
474}
475
476/// Deserialize `T` from JSON text, reporting the dotted path of the failing field under `prefix`.
477///
478/// Decoding from text (not from a [`Value`]) keeps object key order for `IndexMap` fields
479/// regardless of serde_json's `preserve_order` feature.
480fn typed<T: DeserializeOwned>(prefix: &str, json: &[u8]) -> Result<T, DecodeFailure> {
481    let mut de = serde_json::Deserializer::from_slice(json);
482    let value = serde_path_to_error::deserialize(&mut de).map_err(|e| {
483        let inner = e.path().to_string();
484        let path = match (prefix.is_empty(), inner.as_str()) {
485            (true, ".") => String::new(),
486            (true, _) => inner.clone(),
487            (false, ".") => prefix.to_owned(),
488            (false, _) => format!("{prefix}.{inner}"),
489        };
490        // serde_json reports a missing field on the parent path; append it for precision.
491        let msg = e.inner().to_string();
492        let path = match msg
493            .strip_prefix("missing field `")
494            .and_then(|r| r.split('`').next())
495        {
496            Some(field) if path.is_empty() => field.to_owned(),
497            Some(field) => format!("{path}.{field}"),
498            None => path,
499        };
500        DecodeFailure { path, detail: msg }
501    })?;
502    de.end().map_err(|e| DecodeFailure {
503        path: prefix.to_owned(),
504        detail: e.to_string(),
505    })?;
506    Ok(value)
507}
508
509#[derive(Deserialize)]
510struct Envelope {
511    model: String,
512    #[serde(default)]
513    usage: Usage,
514    answers: IndexMap<String, Box<RawValue>>,
515}
516
517/// A successfully decoded System One body.
518pub(crate) struct DecodedSystemOne {
519    pub model: String,
520    pub usage: Usage,
521    pub answers: IndexMap<String, Answer>,
522    pub raw: Value,
523}
524
525pub(crate) fn decode_system_one(body: &[u8]) -> Result<DecodedSystemOne, DecodeFailure> {
526    let env: Envelope = typed("", body)?;
527    let mut answers = IndexMap::with_capacity(env.answers.len());
528    for (name, value) in env.answers {
529        let prefix = format!("answers.{name}");
530        let json = value.get();
531        let tag = serde_json::from_str::<Value>(json)
532            .ok()
533            .and_then(|v| v.get("type").and_then(Value::as_str).map(str::to_owned));
534        let Some(tag) = tag else {
535            return Err(DecodeFailure {
536                path: format!("{prefix}.type"),
537                detail: "missing or non-string answer type".into(),
538            });
539        };
540        let answer = match tag.as_str() {
541            "noul" => Answer::Noul(typed(&prefix, json.as_bytes())?),
542            "choice" => Answer::Choice(typed(&prefix, json.as_bytes())?),
543            "score" => Answer::Score(typed(&prefix, json.as_bytes())?),
544            "box" => Answer::Box(typed(&prefix, json.as_bytes())?),
545            other => {
546                tracing::warn!(answer = %name, r#type = %other, "ignoring answer with unrecognized type");
547                continue;
548            }
549        };
550        answers.insert(name, answer);
551    }
552    // The envelope parsed, so the body is valid JSON.
553    let raw = serde_json::from_slice(body).unwrap_or(Value::Null);
554    Ok(DecodedSystemOne {
555        model: env.model,
556        usage: env.usage,
557        answers,
558        raw,
559    })
560}
561
562#[derive(Deserialize)]
563struct ModelList {
564    models: Vec<ModelMetadata>,
565}
566
567pub(crate) fn decode_models(body: &[u8]) -> Result<(Vec<ModelMetadata>, Value), DecodeFailure> {
568    let list: ModelList = typed("", body)?;
569    let raw = serde_json::from_slice(body).unwrap_or(Value::Null);
570    Ok((list.models, raw))
571}
572
573#[cfg(test)]
574mod tests {
575    use super::*;
576    use serde_json::json;
577
578    fn sample() -> Value {
579        json!({
580            "model": "jev-latest",
581            "answers": {
582                "department": {"type": "choice", "choice": "technical",
583                    "probabilities": {"billing": 0.159, "technical": 0.84, "sales": 0.001}, "confidence": 0.596},
584                "frustration": {"type": "score", "score": 1.6,
585                    "legend": {"0": "Calm", "1": "Frustrated", "2": "Very angry"},
586                    "probabilities": {"0": 0.05, "1": 0.3, "2": 0.65}, "confidence": 0.78},
587                "is_urgent": {"type": "noul", "noul": 0.999},
588                "future": {"type": "span", "start": 3}
589            },
590            "usage": {"input_tokens": 312, "output_tokens": 48, "extra": true}
591        })
592    }
593
594    fn decode(v: Value) -> Result<DecodedSystemOne, DecodeFailure> {
595        decode_system_one(&serde_json::to_vec(&v).unwrap())
596    }
597
598    #[test]
599    fn decodes_all_types_and_skips_unknown() {
600        let DecodedSystemOne {
601            model,
602            usage,
603            answers,
604            raw,
605        } = decode(sample()).ok().unwrap();
606        assert_eq!(model, "jev-latest");
607        assert_eq!(usage.input_tokens, Some(312));
608        assert_eq!(answers.len(), 3);
609        assert_eq!(raw["answers"]["future"]["start"], json!(3));
610        let Answer::Score(s) = &answers["frustration"] else {
611            panic!()
612        };
613        assert_eq!(s.legend[&2], json!("Very angry"));
614        assert_eq!(s.most_likely_level(), Some(2));
615        assert_eq!(s.rounded_level(), 2);
616        let Answer::Choice(c) = &answers["department"] else {
617            panic!()
618        };
619        assert_eq!(c.ranked()[0], ("technical", 0.84));
620    }
621
622    #[test]
623    fn serializes_back_to_the_wire_shape() {
624        let mut wire = sample();
625        wire["answers"].as_object_mut().unwrap().remove("future");
626        wire["usage"].as_object_mut().unwrap().remove("extra");
627        let d = decode(wire.clone()).ok().unwrap();
628        let res = SystemOneResponse {
629            model: d.model,
630            usage: d.usage,
631            answers: d.answers,
632            raw: d.raw,
633            meta: ResponseMeta {
634                status: StatusCode::OK,
635                headers: HeaderMap::new(),
636                attempts: 1,
637            },
638        };
639        // The JSON the API sent, and it decodes to the same answers.
640        let body = serde_json::to_vec(&res).unwrap();
641        assert_eq!(serde_json::from_slice::<Value>(&body).unwrap(), wire);
642        let again = decode_system_one(&body).ok().unwrap();
643        assert_eq!(again.model, res.model);
644        assert_eq!(again.usage, res.usage);
645        assert_eq!(again.answers, res.answers);
646
647        for (name, answer) in &res.answers {
648            assert_eq!(answer.kind().to_string(), wire["answers"][name]["type"]);
649            let text = serde_json::to_string(answer).unwrap();
650            assert_eq!(serde_json::from_str::<Answer>(&text).unwrap(), *answer);
651            assert_eq!(
652                serde_json::from_str::<Value>(&text).unwrap(),
653                wire["answers"][name]
654            );
655        }
656        // Server order survives the round trip, byte for byte.
657        let text = r#"{"type":"choice","choice":"z","probabilities":{"z":0.5,"a":0.3,"m":0.2},"confidence":0.1}"#;
658        let answer: Answer = serde_json::from_str(text).unwrap();
659        assert_eq!(serde_json::to_string(&answer).unwrap(), text);
660
661        assert_eq!(serde_json::to_value(Usage::default()).unwrap(), json!({}));
662        assert!(serde_json::from_value::<Answer>(json!({"type": "span"})).is_err());
663        assert!(serde_json::from_value::<Answer>(json!({"type": "noul"})).is_err());
664
665        let body =
666            br#"{"models":[{"name":"jev-latest","description":"d","release_date":"2025-01-01"}]}"#;
667        let (models, raw) = decode_models(body).ok().unwrap();
668        let list = ListModelsResponse {
669            models,
670            raw: raw.clone(),
671            meta: res.meta.clone(),
672        };
673        assert_eq!(serde_json::to_value(&list).unwrap(), raw);
674    }
675
676    #[test]
677    fn preserves_server_order_of_probabilities() {
678        let body = br#"{"model":"m","usage":{},"answers":{"c":{"type":"choice","choice":"z",
679            "probabilities":{"z":0.5,"a":0.3,"m":0.2},"confidence":0.1}}}"#;
680        let d = decode_system_one(body).ok().unwrap();
681        let Answer::Choice(c) = &d.answers["c"] else {
682            panic!()
683        };
684        let keys: Vec<_> = c.probabilities.keys().map(String::as_str).collect();
685        assert_eq!(keys, ["z", "a", "m"]);
686    }
687
688    #[test]
689    fn usage_may_be_empty_or_absent() {
690        let d = decode(json!({"model": "m", "answers": {}, "usage": {}}))
691            .ok()
692            .unwrap();
693        assert_eq!(d.usage, Usage::default());
694        let d = decode(json!({"model": "m", "answers": {}})).ok().unwrap();
695        assert_eq!(d.usage, Usage::default());
696    }
697
698    #[test]
699    fn rejects_non_json_and_trailing_content() {
700        assert_eq!(decode_system_one(b"<html>").err().unwrap().path, "");
701        let mut body = serde_json::to_vec(&sample()).unwrap();
702        body.extend_from_slice(b" trailing");
703        assert!(decode_system_one(&body).is_err());
704    }
705
706    #[test]
707    fn reports_precise_paths() {
708        let mut v = sample();
709        v["answers"]["department"]
710            .as_object_mut()
711            .unwrap()
712            .remove("confidence");
713        assert_eq!(
714            decode(v).err().unwrap().path,
715            "answers.department.confidence"
716        );
717
718        let mut v = sample();
719        v["answers"]["frustration"]["probabilities"]["1"] = json!("high");
720        assert_eq!(
721            decode(v).err().unwrap().path,
722            "answers.frustration.probabilities.1"
723        );
724
725        let mut v = sample();
726        v["answers"]["is_urgent"]["type"] = json!(7);
727        assert_eq!(decode(v).err().unwrap().path, "answers.is_urgent.type");
728
729        let mut v = sample();
730        v.as_object_mut().unwrap().remove("model");
731        assert_eq!(decode(v).err().unwrap().path, "model");
732    }
733}