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}