Skip to main content

jevrs_core/
response.rs

1use alloc::{
2    boxed::Box,
3    collections::BTreeMap,
4    format,
5    string::{String, ToString},
6    vec::Vec,
7};
8use core::{any::Any, fmt, ops::Index};
9
10use serde::Deserialize;
11
12use crate::{
13    ChoiceAnswer, Confidence, DynChoiceAnswer, DynScoreAnswer, Error, Handle, Levels, Model,
14    NoulAnswer, Options, Probability, Question, Questions, ScoreAnswer, Usage,
15    builder::{BatchId, Criteria},
16};
17
18pub(crate) type AnswerSlot = Box<dyn Any + Send + Sync>;
19pub(crate) type Decoder = fn(&str, Option<&Criteria>, WireAnswer) -> Result<AnswerSlot, Error>;
20
21#[derive(Deserialize)]
22pub(crate) struct WireResponse {
23    pub(crate) model: Model,
24    pub(crate) answers: BTreeMap<String, WireAnswer>,
25    pub(crate) usage: Usage,
26}
27
28/// Eagerly decoded answers for one [`Questions`] batch.
29///
30/// Use this for a runtime-built batch and retrieve answers with their typed
31/// [`Handle`] values. Use [`crate::Answered`] for a static
32/// [`crate::QuestionSet`]. The response model and token counts remain available
33/// through [`Answers::model`] and [`Answers::usage`].
34pub struct Answers {
35    model: Model,
36    usage: Usage,
37    batch: BatchId,
38    slots: Vec<AnswerSlot>,
39}
40
41impl fmt::Debug for Answers {
42    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
43        formatter
44            .debug_struct("Answers")
45            .field("model", &self.model)
46            .field("usage", &self.usage)
47            .field("batch", &self.batch)
48            .field("slot_count", &self.slots.len())
49            .finish()
50    }
51}
52
53impl Answers {
54    /// Retrieves the typed answer bound to a handle from the same batch.
55    ///
56    /// ```
57    /// use jevrs_core::{Questions, decode};
58    ///
59    /// let mut questions = Questions::new();
60    /// let urgent = questions.noul("is_urgent", "Does this convey urgency?")?;
61    /// let body = br#"{
62    ///   "model":"jev-1.13.0",
63    ///   "answers":{"is_urgent":{"type":"noul","noul":0.95}},
64    ///   "usage":{"input_tokens":414,"output_tokens":73}
65    /// }"#;
66    /// let answers = decode(&questions, body)?;
67    /// assert!((answers.get(urgent).p.get() - 0.95).abs() < f64::EPSILON);
68    /// # Ok::<(), jevrs_core::Error>(())
69    /// ```
70    ///
71    /// # Panics
72    ///
73    /// Panics when `handle` was created by a different [`Questions`] batch. The
74    /// panic message identifies both batch IDs.
75    #[must_use]
76    pub fn get<Q: Question>(&self, handle: Handle<Q>) -> &Q::Answer {
77        assert_eq!(
78            handle.batch, self.batch,
79            "handle batch {:?} does not match answers batch {:?}",
80            handle.batch, self.batch
81        );
82        let index = usize::try_from(handle.idx).unwrap_or(usize::MAX);
83        let Some(answer) = self
84            .slots
85            .get(index)
86            .and_then(|slot| slot.downcast_ref::<Q::Answer>())
87        else {
88            unreachable!("a handle created by this batch has a matching answer slot");
89        };
90        answer
91    }
92
93    /// Returns the concrete model version for logs and reproducibility.
94    #[must_use]
95    pub fn model(&self) -> &str {
96        self.model.as_ref()
97    }
98
99    /// Returns token counts for observability and cost accounting.
100    #[must_use]
101    pub const fn usage(&self) -> Usage {
102        self.usage
103    }
104}
105
106impl<Q: Question> Index<Handle<Q>> for Answers {
107    type Output = Q::Answer;
108
109    /// Retrieves the answer bound to `handle`.
110    ///
111    /// # Panics
112    ///
113    /// Panics when `handle` was created by a different [`Questions`] batch. The
114    /// panic message identifies both batch IDs.
115    fn index(&self, handle: Handle<Q>) -> &Self::Output {
116        self.get(handle)
117    }
118}
119
120/// Decodes and validates a Jev response for `questions` without network I/O.
121///
122/// Use this on a successful HTTP response produced for the same [`Questions`]
123/// batch. Use [`crate::classify`] for an unsuccessful HTTP status.
124///
125/// ```
126/// use jevrs_core::{Questions, decode};
127///
128/// let mut questions = Questions::new();
129/// let urgent = questions.noul("is_urgent", "Does this convey urgency?")?;
130/// let body = br#"{
131///   "model":"jev-1.13.0",
132///   "answers":{"is_urgent":{"type":"noul","noul":0.95}},
133///   "usage":{"input_tokens":414,"output_tokens":73}
134/// }"#;
135/// let answers = decode(&questions, body)?;
136/// assert!(answers[urgent].is_yes(0.9));
137/// assert_eq!(answers.model(), "jev-1.13.0");
138/// # Ok::<(), jevrs_core::Error>(())
139/// ```
140///
141/// # Errors
142///
143/// Returns [`Error::Json`] for malformed JSON or an out-of-range probability.
144/// Returns [`Error::Protocol`] when answer IDs, types, keys, legends, or scores
145/// do not match the originating questions.
146pub fn decode(questions: &Questions, body: &[u8]) -> Result<Answers, Error> {
147    let mut response: WireResponse = serde_json::from_slice(body)?;
148
149    let mut slots = Vec::with_capacity(questions.entries.len());
150    for entry in &questions.entries {
151        let Some(answer) = response.answers.remove(&entry.id) else {
152            return Err(Error::Protocol {
153                id: Some(entry.id.clone()),
154                reason: "missing answer".into(),
155            });
156        };
157        slots.push(entry.decode(answer)?);
158    }
159    if let Some(id) = response.answers.keys().next().cloned() {
160        return Err(Error::Protocol {
161            id: Some(id),
162            reason: "answer for unknown question".into(),
163        });
164    }
165
166    Ok(Answers {
167        model: response.model,
168        usage: response.usage,
169        batch: questions.batch,
170        slots,
171    })
172}
173
174#[derive(Deserialize)]
175#[serde(tag = "type")]
176pub(crate) enum WireAnswer {
177    #[serde(rename = "noul")]
178    Noul { noul: Probability },
179    #[serde(rename = "choice")]
180    Choice {
181        choice: String,
182        probabilities: BTreeMap<String, Probability>,
183        confidence: Confidence,
184    },
185    #[serde(rename = "score")]
186    Score {
187        score: f64,
188        legend: BTreeMap<String, String>,
189        probabilities: BTreeMap<String, Probability>,
190        confidence: Confidence,
191    },
192    #[serde(other)]
193    Unknown,
194}
195
196impl WireAnswer {
197    pub(crate) const fn kind(&self) -> &'static str {
198        match self {
199            Self::Noul { .. } => "noul",
200            Self::Choice { .. } => "choice",
201            Self::Score { .. } => "score",
202            Self::Unknown => "unknown",
203        }
204    }
205}
206
207fn protocol(id: &str, reason: String) -> Error {
208    Error::Protocol {
209        id: Some(id.into()),
210        reason,
211    }
212}
213
214fn wrong_type(id: &str, expected: &str, answer: &WireAnswer) -> Error {
215    protocol(
216        id,
217        format!("expected {expected} answer, got {}", answer.kind()),
218    )
219}
220
221fn choice_keys<'a>(id: &str, criteria: Option<&'a Criteria>) -> Result<Vec<&'a str>, Error> {
222    match criteria {
223        Some(Criteria::Map(criteria)) => {
224            Ok(criteria.0.iter().map(|(key, _)| key.as_str()).collect())
225        }
226        _ => Err(protocol(id, "choice criteria are unavailable".into())),
227    }
228}
229
230fn score_levels<'a>(id: &str, criteria: Option<&'a Criteria>) -> Result<&'a [String], Error> {
231    match criteria {
232        Some(Criteria::Levels(levels)) => Ok(levels),
233        _ => Err(protocol(id, "score criteria are unavailable".into())),
234    }
235}
236
237fn validate_key_set<T>(
238    id: &str,
239    field: &str,
240    expected: &[&str],
241    actual: &BTreeMap<String, T>,
242) -> Result<(), Error> {
243    for key in expected {
244        if !actual.contains_key(*key) {
245            return Err(protocol(id, format!("{field} missing key {key:?}")));
246        }
247    }
248    for key in actual.keys() {
249        if !expected.contains(&key.as_str()) {
250            return Err(protocol(id, format!("{field} has unexpected key {key:?}")));
251        }
252    }
253    Ok(())
254}
255
256fn ordered_probabilities(
257    id: &str,
258    expected: &[&str],
259    probabilities: &BTreeMap<String, Probability>,
260) -> Result<Vec<Probability>, Error> {
261    let ordered = expected
262        .iter()
263        .map(|key| {
264            probabilities
265                .get(*key)
266                .copied()
267                .ok_or_else(|| protocol(id, format!("probabilities missing key {key:?}")))
268        })
269        .collect::<Result<Vec<_>, _>>()?;
270    if probabilities.len() != expected.len()
271        && let Some(key) = probabilities
272            .keys()
273            .find(|key| !expected.contains(&key.as_str()))
274    {
275        return Err(protocol(
276            id,
277            format!("probabilities has unexpected key {key:?}"),
278        ));
279    }
280    Ok(ordered)
281}
282
283pub(crate) fn decode_noul(
284    id: &str,
285    _criteria: Option<&Criteria>,
286    answer: WireAnswer,
287) -> Result<AnswerSlot, Error> {
288    match answer {
289        WireAnswer::Noul { noul } => Ok(Box::new(NoulAnswer { p: noul })),
290        other => Err(wrong_type(id, "noul", &other)),
291    }
292}
293
294struct ChoiceParts<'a> {
295    choice: String,
296    keys: Vec<&'a str>,
297    ordered: Vec<Probability>,
298    confidence: Confidence,
299}
300
301fn choice_parts<'a>(
302    id: &str,
303    criteria: Option<&'a Criteria>,
304    answer: WireAnswer,
305) -> Result<ChoiceParts<'a>, Error> {
306    let WireAnswer::Choice {
307        choice,
308        probabilities,
309        confidence,
310    } = answer
311    else {
312        return Err(wrong_type(id, "choice", &answer));
313    };
314    let keys = choice_keys(id, criteria)?;
315    let ordered = ordered_probabilities(id, &keys, &probabilities)?;
316    Ok(ChoiceParts {
317        choice,
318        keys,
319        ordered,
320        confidence,
321    })
322}
323
324fn unknown_choice(id: &str, choice: &str) -> Error {
325    protocol(
326        id,
327        format!("choice key {choice:?} is not in the option set"),
328    )
329}
330
331pub(crate) fn decode_static_choice<O: Options>(
332    id: &str,
333    criteria: Option<&Criteria>,
334    answer: WireAnswer,
335) -> Result<AnswerSlot, Error> {
336    let parts = choice_parts(id, criteria, answer)?;
337    let Some(pick) = O::from_key(&parts.choice) else {
338        return Err(unknown_choice(id, &parts.choice));
339    };
340    let probs = O::map_from_fn(|option| parts.ordered[option.index()]);
341    Ok(Box::new(ChoiceAnswer::<O> {
342        pick,
343        probs,
344        confidence: parts.confidence,
345    }))
346}
347
348pub(crate) fn decode_dynamic_choice(
349    id: &str,
350    criteria: Option<&Criteria>,
351    answer: WireAnswer,
352) -> Result<AnswerSlot, Error> {
353    let ChoiceParts {
354        choice,
355        keys,
356        ordered,
357        confidence,
358    } = choice_parts(id, criteria, answer)?;
359    if !keys.contains(&choice.as_str()) {
360        return Err(unknown_choice(id, &choice));
361    }
362    let probs = keys.into_iter().map(String::from).zip(ordered).collect();
363    Ok(Box::new(DynChoiceAnswer {
364        pick: choice,
365        probs,
366        confidence,
367    }))
368}
369
370struct ScoreParts {
371    score: f64,
372    legend: BTreeMap<String, String>,
373    probabilities: BTreeMap<String, Probability>,
374    confidence: Confidence,
375}
376
377fn score_parts(id: &str, answer: WireAnswer) -> Result<ScoreParts, Error> {
378    let WireAnswer::Score {
379        score,
380        legend,
381        probabilities,
382        confidence,
383    } = answer
384    else {
385        return Err(wrong_type(id, "score", &answer));
386    };
387    Ok(ScoreParts {
388        score,
389        legend,
390        probabilities,
391        confidence,
392    })
393}
394
395#[allow(clippy::cast_precision_loss)]
396fn decode_score_parts(
397    id: &str,
398    criteria: Option<&Criteria>,
399    answer: WireAnswer,
400) -> Result<(ScoreParts, Vec<String>, Vec<Probability>), Error> {
401    let parts = score_parts(id, answer)?;
402    let levels = score_levels(id, criteria)?;
403    let keys = (0..levels.len())
404        .map(|index| index.to_string())
405        .collect::<Vec<_>>();
406    let key_refs = keys.iter().map(String::as_str).collect::<Vec<_>>();
407    let probabilities = ordered_probabilities(id, &key_refs, &parts.probabilities)?;
408    validate_key_set(id, "legend", &key_refs, &parts.legend)?;
409    let maximum = levels.len().saturating_sub(1) as f64;
410    if !(0.0..=maximum).contains(&parts.score) {
411        return Err(protocol(
412            id,
413            format!("score {} is outside 0..={maximum}", parts.score),
414        ));
415    }
416    Ok((parts, keys, probabilities))
417}
418
419pub(crate) fn decode_static_score<L: Levels>(
420    id: &str,
421    criteria: Option<&Criteria>,
422    answer: WireAnswer,
423) -> Result<AnswerSlot, Error> {
424    let (parts, keys, ordered) = decode_score_parts(id, criteria, answer)?;
425    for (level, key) in L::all().iter().zip(&keys) {
426        let Some(actual) = parts.legend.get(key) else {
427            return Err(protocol(id, format!("legend missing key {key:?}")));
428        };
429        let expected = level.description();
430        if actual != expected {
431            return Err(protocol(
432                id,
433                format!("legend key {key:?} expected {expected:?}, got {actual:?}"),
434            ));
435        }
436    }
437    let probs = L::map_from_fn(|level| ordered[level.index()]);
438    Ok(Box::new(ScoreAnswer::<L>::new(
439        parts.score,
440        probs,
441        parts.confidence,
442    )))
443}
444
445pub(crate) fn decode_dynamic_score(
446    id: &str,
447    criteria: Option<&Criteria>,
448    answer: WireAnswer,
449) -> Result<AnswerSlot, Error> {
450    let (parts, keys, probabilities) = decode_score_parts(id, criteria, answer)?;
451    let legend = keys
452        .iter()
453        .map(|key| {
454            parts
455                .legend
456                .get(key)
457                .cloned()
458                .ok_or_else(|| protocol(id, format!("legend missing key {key:?}")))
459        })
460        .collect::<Result<Vec<_>, _>>()?;
461    Ok(Box::new(DynScoreAnswer::new(
462        parts.score,
463        probabilities,
464        legend,
465        parts.confidence,
466    )))
467}
468
469#[cfg(test)]
470mod tests {
471    use alloc::{
472        format,
473        string::{String, ToString},
474    };
475
476    use serde_json::json;
477
478    use super::{Answers, WireAnswer, WireResponse, decode};
479    use crate::{
480        ChoiceAnswer, ChoiceQ, DynChoiceAnswer, DynChoiceQ, DynLevels, DynOptions, DynScoreAnswer,
481        DynScoreQ, Error, Handle, Model, NoulAnswer, NoulQ, Questions, ScoreAnswer, ScoreQ, encode,
482        test_support::{Dept, Frustration, TRIAGE_RESPONSE},
483    };
484
485    type StaticHandles = (
486        Handle<NoulQ>,
487        Handle<ChoiceQ<Dept>>,
488        Handle<ScoreQ<Frustration>>,
489    );
490    type DynamicHandles = (Handle<NoulQ>, Handle<DynChoiceQ>, Handle<DynScoreQ>);
491
492    #[test]
493    fn answers_are_send_and_sync() {
494        fn assert_send_sync<T: Send + Sync>() {}
495        assert_send_sync::<Answers>();
496    }
497
498    fn static_triage() -> (Questions, StaticHandles) {
499        let mut questions = Questions::new();
500        let urgent = questions
501            .noul_with(
502                "is_urgent",
503                "Does this convey urgency?",
504                "Explicitly time-sensitive",
505                "No urgency expressed",
506            )
507            .unwrap();
508        let department = questions
509            .choice::<Dept>("department", "Which team should handle this?")
510            .unwrap();
511        let frustration = questions
512            .score::<Frustration>("frustration", "How frustrated is the customer?")
513            .unwrap();
514        (questions, (urgent, department, frustration))
515    }
516
517    fn dynamic_triage() -> (Questions, DynamicHandles) {
518        let mut questions = Questions::new();
519        let urgent = questions
520            .noul_with(
521                "is_urgent",
522                "Does this convey urgency?",
523                "Explicitly time-sensitive",
524                "No urgency expressed",
525            )
526            .unwrap();
527        let department = questions
528            .choice_dyn(
529                "department",
530                "Which team should handle this?",
531                DynOptions::new([
532                    ("billing", Some("Payments, invoicing, refunds")),
533                    ("technical", Some("Bugs, outages, integrations")),
534                    ("sales", None),
535                ])
536                .unwrap(),
537            )
538            .unwrap();
539        let frustration = questions
540            .score_dyn(
541                "frustration",
542                "How frustrated is the customer?",
543                DynLevels::new(["Calm", "Frustrated", "Very angry"]).unwrap(),
544            )
545            .unwrap();
546        (questions, (urgent, department, frustration))
547    }
548
549    fn static_choice_questions() -> Questions {
550        let mut questions = Questions::new();
551        questions.choice::<Dept>("department", "Choose").unwrap();
552        questions
553    }
554
555    fn dynamic_choice_questions() -> Questions {
556        let mut questions = Questions::new();
557        questions
558            .choice_dyn(
559                "department",
560                "Choose",
561                DynOptions::new([
562                    ("billing", None::<&str>),
563                    ("technical", None),
564                    ("sales", None),
565                ])
566                .unwrap(),
567            )
568            .unwrap();
569        questions
570    }
571
572    fn static_score_questions() -> Questions {
573        let mut questions = Questions::new();
574        questions
575            .score::<Frustration>("frustration", "Rate")
576            .unwrap();
577        questions
578    }
579
580    fn dynamic_score_questions() -> Questions {
581        let mut questions = Questions::new();
582        questions
583            .score_dyn(
584                "frustration",
585                "Rate",
586                DynLevels::new(["Calm", "Frustrated", "Very angry"]).unwrap(),
587            )
588            .unwrap();
589        questions
590    }
591
592    fn protocol_reason(questions: &Questions, json: &str) -> String {
593        let answer: WireAnswer = serde_json::from_str(json).unwrap();
594        let error = questions.entries[0].decode(answer).err().unwrap();
595        match error {
596            Error::Protocol { id, reason } => {
597                assert_eq!(id.as_deref(), Some(questions.entries[0].id.as_str()));
598                reason
599            }
600            other => panic!("expected protocol error, got {other:?}"),
601        }
602    }
603
604    fn assert_choice_reason(json: &str, expected: &str) {
605        for questions in [static_choice_questions(), dynamic_choice_questions()] {
606            assert_eq!(protocol_reason(&questions, json), expected);
607        }
608    }
609
610    fn assert_score_reason(json: &str, expected: &str) {
611        for questions in [static_score_questions(), dynamic_score_questions()] {
612            assert_eq!(protocol_reason(&questions, json), expected);
613        }
614    }
615
616    #[test]
617    fn every_question_kind_decodes_its_happy_path() {
618        let mut questions = Questions::new();
619        questions.noul("noul", "Urgent?").unwrap();
620        questions.choice::<Dept>("static_choice", "Choose").unwrap();
621        questions
622            .score::<Frustration>("static_score", "Rate")
623            .unwrap();
624        questions
625            .choice_dyn(
626                "dynamic_choice",
627                "Choose",
628                DynOptions::new([("first", None::<&str>), ("second", None)]).unwrap(),
629            )
630            .unwrap();
631        questions
632            .score_dyn(
633                "dynamic_score",
634                "Rate",
635                DynLevels::new(["Low", "High"]).unwrap(),
636            )
637            .unwrap();
638
639        let noul = questions.entries[0]
640            .decode(serde_json::from_str(r#"{"type":"noul","noul":0.95}"#).unwrap())
641            .unwrap()
642            .downcast::<NoulAnswer>()
643            .unwrap();
644        assert!((noul.p.get() - 0.95).abs() < f64::EPSILON);
645
646        let choice = questions.entries[1]
647            .decode(serde_json::from_str(
648                r#"{"type":"choice","choice":"billing","confidence":0.79,"probabilities":{"billing":0.86,"technical":0.14,"sales":0.0}}"#,
649            ).unwrap())
650            .unwrap()
651            .downcast::<ChoiceAnswer<Dept>>()
652            .unwrap();
653        assert_eq!(choice.pick, Dept::Billing);
654        assert!((choice.probs[Dept::Billing].get() - 0.86).abs() < f64::EPSILON);
655
656        let score = questions.entries[2]
657            .decode(serde_json::from_str(
658                r#"{"type":"score","score":1.05,"confidence":0.93,"legend":{"0":"Calm","1":"Frustrated","2":"Very angry"},"probabilities":{"0":0.0,"1":0.95,"2":0.05}}"#,
659            ).unwrap())
660            .unwrap()
661            .downcast::<ScoreAnswer<Frustration>>()
662            .unwrap();
663        assert_eq!(score.nearest(), Frustration::Frustrated);
664
665        let choice = questions.entries[3]
666            .decode(serde_json::from_str(
667                r#"{"type":"choice","choice":"second","confidence":0.8,"probabilities":{"first":0.2,"second":0.8}}"#,
668            ).unwrap())
669            .unwrap()
670            .downcast::<DynChoiceAnswer>()
671            .unwrap();
672        assert_eq!(choice.pick, "second");
673        assert_eq!(choice.probs[0].0, "first");
674
675        let score = questions.entries[4]
676            .decode(serde_json::from_str(
677                r#"{"type":"score","score":0.75,"confidence":0.9,"legend":{"0":"Server low","1":"Server high"},"probabilities":{"0":0.25,"1":0.75}}"#,
678            ).unwrap())
679            .unwrap()
680            .downcast::<DynScoreAnswer>()
681            .unwrap();
682        assert_eq!(score.legend, ["Server low", "Server high"]);
683    }
684
685    #[test]
686    fn mismatched_answer_types_name_the_expected_and_actual_types() {
687        let mut noul = Questions::new();
688        noul.noul("urgent", "Urgent?").unwrap();
689        assert_eq!(
690            protocol_reason(
691                &noul,
692                r#"{"type":"choice","choice":"x","confidence":0.5,"probabilities":{"x":1.0}}"#
693            ),
694            "expected noul answer, got choice"
695        );
696        assert_choice_reason(
697            r#"{"type":"score","score":0.0,"confidence":0.5,"legend":{"0":"x"},"probabilities":{"0":1.0}}"#,
698            "expected choice answer, got score",
699        );
700        assert_score_reason(
701            r#"{"type":"ranking","ranking":[]}"#,
702            "expected score answer, got unknown",
703        );
704    }
705
706    #[test]
707    fn choice_probabilities_report_a_missing_key() {
708        assert_choice_reason(
709            r#"{"type":"choice","choice":"billing","confidence":0.8,"probabilities":{"billing":0.8,"technical":0.2}}"#,
710            "probabilities missing key \"sales\"",
711        );
712    }
713
714    #[test]
715    fn choice_probabilities_report_an_extra_key() {
716        assert_choice_reason(
717            r#"{"type":"choice","choice":"billing","confidence":0.8,"probabilities":{"billing":0.8,"technical":0.1,"sales":0.1,"other":0.0}}"#,
718            "probabilities has unexpected key \"other\"",
719        );
720    }
721
722    #[test]
723    fn choices_report_an_unknown_selected_key() {
724        assert_choice_reason(
725            r#"{"type":"choice","choice":"other","confidence":0.8,"probabilities":{"billing":0.8,"technical":0.1,"sales":0.1}}"#,
726            "choice key \"other\" is not in the option set",
727        );
728    }
729
730    #[test]
731    fn score_probabilities_report_a_missing_key() {
732        assert_score_reason(
733            r#"{"type":"score","score":1.0,"confidence":0.9,"legend":{"0":"Calm","1":"Frustrated","2":"Very angry"},"probabilities":{"0":0.0,"1":1.0}}"#,
734            "probabilities missing key \"2\"",
735        );
736    }
737
738    #[test]
739    fn score_probabilities_report_an_extra_key() {
740        assert_score_reason(
741            r#"{"type":"score","score":1.0,"confidence":0.9,"legend":{"0":"Calm","1":"Frustrated","2":"Very angry"},"probabilities":{"0":0.0,"1":1.0,"2":0.0,"3":0.0}}"#,
742            "probabilities has unexpected key \"3\"",
743        );
744    }
745
746    #[test]
747    fn score_legends_report_a_missing_key() {
748        assert_score_reason(
749            r#"{"type":"score","score":1.0,"confidence":0.9,"legend":{"0":"Calm","1":"Frustrated"},"probabilities":{"0":0.0,"1":1.0,"2":0.0}}"#,
750            "legend missing key \"2\"",
751        );
752    }
753
754    #[test]
755    fn score_legends_report_an_extra_key() {
756        assert_score_reason(
757            r#"{"type":"score","score":1.0,"confidence":0.9,"legend":{"0":"Calm","1":"Frustrated","2":"Very angry","3":"Other"},"probabilities":{"0":0.0,"1":1.0,"2":0.0}}"#,
758            "legend has unexpected key \"3\"",
759        );
760    }
761
762    #[test]
763    fn static_score_legends_report_mismatched_text() {
764        assert_eq!(
765            protocol_reason(
766                &static_score_questions(),
767                r#"{"type":"score","score":1.0,"confidence":0.9,"legend":{"0":"Calm","1":"Annoyed","2":"Very angry"},"probabilities":{"0":0.0,"1":1.0,"2":0.0}}"#,
768            ),
769            "legend key \"1\" expected \"Frustrated\", got \"Annoyed\""
770        );
771    }
772
773    #[test]
774    fn scores_report_values_outside_the_scale() {
775        assert_score_reason(
776            r#"{"type":"score","score":3.0,"confidence":0.9,"legend":{"0":"Calm","1":"Frustrated","2":"Very angry"},"probabilities":{"0":0.0,"1":1.0,"2":0.0}}"#,
777            "score 3 is outside 0..=2",
778        );
779    }
780
781    #[test]
782    fn recorded_response_parses() {
783        let response: WireResponse = serde_json::from_slice(TRIAGE_RESPONSE).unwrap();
784        assert_eq!(response.model.as_ref(), "jev-1.13.0");
785        assert_eq!(response.answers.len(), 3);
786        assert_eq!(response.usage.input_tokens, 414);
787        assert!(matches!(
788            response.answers["is_urgent"],
789            WireAnswer::Noul { noul } if (noul.get() - 0.95).abs() < f64::EPSILON
790        ));
791    }
792
793    #[test]
794    fn unknown_answer_type_uses_the_catch_all() {
795        let answer: WireAnswer =
796            serde_json::from_str(r#"{"type":"ranking","ranking":["first"]}"#).unwrap();
797        assert!(matches!(answer, WireAnswer::Unknown));
798    }
799
800    #[test]
801    fn out_of_range_probability_is_rejected() {
802        let error = serde_json::from_str::<WireAnswer>(r#"{"type":"noul","noul":1.2}"#)
803            .err()
804            .unwrap();
805        assert!(error.to_string().contains("invalid Probability value 1.2"));
806    }
807
808    #[test]
809    fn static_triage_response_decodes_through_typed_handles() {
810        let (questions, (urgent, department, frustration)) = static_triage();
811        let answers = decode(&questions, TRIAGE_RESPONSE).unwrap();
812
813        assert!((answers[urgent].p.get() - 0.95).abs() < f64::EPSILON);
814        assert_eq!(answers[department].pick, Dept::Billing);
815        assert_eq!(answers[frustration].nearest(), Frustration::Frustrated);
816        assert!((answers[frustration].expected() - 1.05).abs() < f64::EPSILON);
817        assert_eq!(answers.model(), "jev-1.13.0");
818        assert_eq!(answers.usage().input_tokens, 414);
819        assert_eq!(answers.usage().output_tokens, 73);
820    }
821
822    #[test]
823    fn answers_debug_reports_metadata_and_slot_count() {
824        let (questions, _) = static_triage();
825        let answers = decode(&questions, TRIAGE_RESPONSE).unwrap();
826        let debug = format!("{answers:?}");
827
828        assert!(debug.contains("model: Model(\"jev-1.13.0\")"));
829        assert!(debug.contains("input_tokens: 414"));
830        assert!(debug.contains("batch: BatchId("));
831        assert!(debug.contains("slot_count: 3"));
832    }
833
834    #[test]
835    fn dynamic_triage_response_decodes_through_typed_handles() {
836        let (questions, (urgent, department, frustration)) = dynamic_triage();
837        let answers = decode(&questions, TRIAGE_RESPONSE).unwrap();
838
839        assert!((answers.get(urgent).p.get() - 0.95).abs() < f64::EPSILON);
840        assert_eq!(answers.get(department).pick, "billing");
841        assert_eq!(answers.get(frustration).nearest(), 1);
842        assert!((answers.get(frustration).expected() - 1.05).abs() < f64::EPSILON);
843    }
844
845    #[test]
846    fn malformed_json_is_a_json_error() {
847        let (questions, _) = static_triage();
848        assert!(matches!(decode(&questions, b"{"), Err(Error::Json(_))));
849    }
850
851    #[test]
852    fn missing_answer_names_the_question() {
853        let mut questions = Questions::new();
854        questions.noul("is_urgent", "Urgent?").unwrap();
855        questions.noul("department", "Billing?").unwrap();
856        let body = br#"{
857          "model":"jev-1.13.0",
858          "answers":{"is_urgent":{"type":"noul","noul":0.95}},
859          "usage":{"input_tokens":414,"output_tokens":73}
860        }"#;
861
862        assert!(matches!(
863            decode(&questions, body),
864            Err(Error::Protocol { id: Some(id), reason })
865                if id == "department" && reason == "missing answer"
866        ));
867    }
868
869    #[test]
870    fn extra_answer_names_the_unknown_question() {
871        let mut questions = Questions::new();
872        questions.noul("is_urgent", "Urgent?").unwrap();
873        let body = br#"{
874          "model":"jev-1.13.0",
875          "answers":{
876            "is_urgent":{"type":"noul","noul":0.95},
877            "mystery":{"type":"noul","noul":0.5}
878          },
879          "usage":{"input_tokens":414,"output_tokens":73}
880        }"#;
881
882        assert!(matches!(
883            decode(&questions, body),
884            Err(Error::Protocol { id: Some(id), reason })
885                if id == "mystery" && reason == "answer for unknown question"
886        ));
887    }
888
889    #[test]
890    #[should_panic(expected = "does not match answers batch")]
891    fn handle_from_another_batch_panics() {
892        let mut first = Questions::new();
893        let first_handle = first.noul("is_urgent", "Urgent?").unwrap();
894        let answers = decode(
895            &first,
896            br#"{"model":"jev-1.13.0","answers":{"is_urgent":{"type":"noul","noul":0.95}},"usage":{"input_tokens":1,"output_tokens":1}}"#,
897        )
898        .unwrap();
899        let mut second = Questions::new();
900        let second_handle = second.noul("is_urgent", "Urgent?").unwrap();
901        let _ = first_handle;
902
903        let _ = answers.get(second_handle);
904    }
905
906    #[test]
907    fn recorded_request_and_response_work_end_to_end() {
908        let (questions, (urgent, department, frustration)) = static_triage();
909        let request = encode(
910            &Model::LATEST,
911            &"Help! My payouts have been failing for 3 days.",
912            &questions,
913        )
914        .unwrap();
915        let request: serde_json::Value = serde_json::from_slice(&request).unwrap();
916        assert_eq!(request["model"], json!("jev-latest"));
917        assert_eq!(request["questions"].as_object().unwrap().len(), 3);
918        assert_eq!(
919            request["questions"]["frustration"]["criteria"],
920            json!(["Calm", "Frustrated", "Very angry"])
921        );
922
923        let answers = decode(&questions, TRIAGE_RESPONSE).unwrap();
924        assert!(answers[urgent].is_yes(0.9));
925        assert_eq!(answers[department].pick, Dept::Billing);
926        assert_eq!(answers[frustration].nearest(), Frustration::Frustrated);
927    }
928}