1use 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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
24#[non_exhaustive]
25pub struct NoulAnswer {
26 pub noul: f64,
28}
29
30impl NoulAnswer {
31 pub fn is_yes(&self, threshold: f64) -> bool {
33 self.noul >= threshold
34 }
35}
36
37#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
39#[non_exhaustive]
40pub struct ChoiceAnswer {
41 pub choice: String,
43 pub probabilities: IndexMap<String, f64>,
45 pub confidence: f64,
47}
48
49impl ChoiceAnswer {
50 pub fn parse<T: FromStr>(&self) -> Result<T, T::Err> {
56 self.choice.parse()
57 }
58
59 pub fn probability(&self, label: &str) -> Option<f64> {
61 self.probabilities.get(label).copied()
62 }
63
64 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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
78#[non_exhaustive]
79pub struct ScoreAnswer {
80 pub score: f64,
82 pub confidence: f64,
84 pub legend: BTreeMap<u32, Value>,
86 pub probabilities: BTreeMap<u32, f64>,
88}
89
90impl ScoreAnswer {
91 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 pub fn rounded_level(&self) -> u32 {
101 self.score.round().max(0.0) as u32
102 }
103}
104
105#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
108#[non_exhaustive]
109pub struct BoundingBox {
110 pub top: f64,
112 pub bottom: f64,
114 pub left: f64,
116 pub right: f64,
118}
119
120impl BoundingBox {
121 pub fn width(&self) -> f64 {
123 self.right - self.left
124 }
125
126 pub fn height(&self) -> f64 {
128 self.bottom - self.top
129 }
130
131 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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
146#[non_exhaustive]
147pub struct BoxAnswer {
148 #[serde(rename = "box")]
150 pub bounds: BoundingBox,
151 pub confidence: f64,
153}
154
155#[derive(Debug, Clone, PartialEq)]
157#[non_exhaustive]
158pub enum Answer {
159 Noul(NoulAnswer),
161 Choice(ChoiceAnswer),
163 Score(ScoreAnswer),
165 Box(BoxAnswer),
167}
168
169#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
171#[non_exhaustive]
172pub enum AnswerKind {
173 Noul,
175 Choice,
177 Score,
179 Box,
181}
182
183impl AnswerKind {
184 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 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 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
223impl 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
250impl<'de> Deserialize<'de> for Answer {
252 fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
253 #[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#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
310#[non_exhaustive]
311pub struct Usage {
312 #[serde(default, skip_serializing_if = "Option::is_none")]
314 pub input_tokens: Option<u64>,
315 #[serde(default, skip_serializing_if = "Option::is_none")]
317 pub output_tokens: Option<u64>,
318}
319
320#[derive(Debug, Clone)]
322#[non_exhaustive]
323pub struct ResponseMeta {
324 pub status: StatusCode,
326 pub headers: HeaderMap,
328 pub attempts: u32,
330}
331
332impl ResponseMeta {
333 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#[derive(Debug, Clone)]
343#[non_exhaustive]
344pub struct SystemOneResponse {
345 pub model: String,
347 pub usage: Usage,
349 pub answers: IndexMap<String, Answer>,
352 pub raw: Value,
355 pub meta: ResponseMeta,
357}
358
359impl SystemOneResponse {
360 pub fn request_id(&self) -> Option<&str> {
362 self.meta.request_id()
363 }
364
365 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 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 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 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 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 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 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
422impl 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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
437#[non_exhaustive]
438pub struct ModelMetadata {
439 pub name: String,
441 pub description: String,
443 pub release_date: String,
445}
446
447impl 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#[derive(Debug, Clone)]
458#[non_exhaustive]
459pub struct ListModelsResponse {
460 pub models: Vec<ModelMetadata>,
462 pub raw: Value,
464 pub meta: ResponseMeta,
466}
467
468pub(crate) struct DecodeFailure {
472 pub path: String,
473 pub detail: String,
474}
475
476fn 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 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
517pub(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 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 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 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}