Skip to main content

typesafe_ai/
response.rs

1use std::collections::BTreeMap;
2
3use http::HeaderMap;
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6
7/// A successful System One response.
8#[derive(Debug, Clone, PartialEq, Deserialize)]
9pub struct Response {
10    /// Model that produced the answers.
11    pub model: String,
12    /// Answers keyed by the request's question identifiers.
13    pub answers: BTreeMap<String, Answer>,
14    /// Token counts, when reported by the API.
15    #[serde(default)]
16    pub usage: Option<Usage>,
17    /// Value of the `x-typesafe-request-id` response header, when present.
18    #[serde(skip)]
19    pub request_id: Option<String>,
20    /// HTTP response headers.
21    #[serde(skip)]
22    pub headers: HeaderMap,
23    /// Original response body bytes, preserving JSON number spelling and precision.
24    ///
25    /// Populated by the HTTP clients; empty when deserializing this type directly.
26    /// Parse these bytes with an exact-decimal parser when binary floating-point
27    /// approximations in [`Answer`] are unsuitable.
28    #[serde(skip)]
29    pub raw_body: Vec<u8>,
30}
31
32impl Response {
33    /// Returns an answer by its question identifier.
34    pub fn answer(&self, id: &str) -> Option<&Answer> {
35        self.answers.get(id)
36    }
37}
38
39/// Token counts reported for a request.
40///
41/// Counts remain optional for forward compatibility with responses that omit either
42/// field.
43#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
44pub struct Usage {
45    /// Number of input tokens, when reported.
46    #[serde(default)]
47    pub input_tokens: Option<u64>,
48    /// Number of output tokens, when reported.
49    #[serde(default)]
50    pub output_tokens: Option<u64>,
51}
52
53/// A typed answer returned by System One.
54///
55/// Numeric fields use `f64` for convenient comparisons and arithmetic. For exact JSON
56/// number preservation, use [`Response::raw_body`].
57#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
58#[serde(tag = "type", rename_all = "lowercase")]
59pub enum Answer {
60    /// A yes/no answer represented as the probability of yes.
61    Noul {
62        /// Probability of a positive answer.
63        noul: f64,
64    },
65    /// The selected option and its probability distribution.
66    Choice {
67        /// Selected option.
68        choice: String,
69        /// Probability for each option.
70        probabilities: BTreeMap<String, f64>,
71        /// Confidence derived from the option distribution.
72        confidence: f64,
73    },
74    /// An expected score and its probability distribution.
75    Score {
76        /// Probability-weighted position across the ordered score levels.
77        score: f64,
78        /// Rubric descriptions keyed by score level.
79        legend: BTreeMap<String, Value>,
80        /// Probability for each score level.
81        probabilities: BTreeMap<String, f64>,
82        /// Confidence derived from the level distribution.
83        confidence: f64,
84    },
85}
86
87impl Answer {
88    /// Returns the Noul probability for a Noul answer.
89    pub fn noul(&self) -> Option<f64> {
90        match self {
91            Self::Noul { noul } => Some(*noul),
92            _ => None,
93        }
94    }
95
96    /// Returns the selected label for a Choice answer.
97    pub fn choice(&self) -> Option<&str> {
98        match self {
99            Self::Choice { choice, .. } => Some(choice),
100            _ => None,
101        }
102    }
103
104    /// Returns the expected score for a Score answer.
105    pub fn score(&self) -> Option<f64> {
106        match self {
107            Self::Score { score, .. } => Some(*score),
108            _ => None,
109        }
110    }
111
112    /// Returns distribution-derived confidence for Choice and Score answers.
113    ///
114    /// This is `None` for Noul because its probability is the answer itself.
115    pub fn confidence(&self) -> Option<f64> {
116        match self {
117            Self::Choice { confidence, .. } | Self::Score { confidence, .. } => Some(*confidence),
118            Self::Noul { .. } => None,
119        }
120    }
121
122    /// Returns the complete distribution for Choice and Score answers.
123    pub fn probabilities(&self) -> Option<&BTreeMap<String, f64>> {
124        match self {
125            Self::Choice { probabilities, .. } | Self::Score { probabilities, .. } => {
126                Some(probabilities)
127            }
128            Self::Noul { .. } => None,
129        }
130    }
131}