Skip to main content

maple_sdk/
system_one.rs

1//! System One: typed decisions with calibrated probabilities (`POST /v1/systemone`).
2//!
3//! A request carries a JSON `state` and named questions of three types. Each
4//! question is answered with one masked single-token decision on Continuum's
5//! GLM-5.3-Flash, so the response holds probabilities rather than text:
6//!
7//! - `noul`: the probability that the statement is true;
8//! - `choice`: a distribution over the options, in the order they were given;
9//! - `score`: the expected level on an ordered scale, with the per-level
10//!   distribution and a legend keyed by level number.
11//!
12//! Choice options are numbered in the order the caller lists them, so the SDK
13//! keeps that order ([`OrderedEntries`]) instead of sorting keys as a map would.
14
15use serde::de::{MapAccess, Visitor};
16use serde::{Deserialize, Deserializer, Serialize, Serializer};
17use serde_json::Value;
18use std::fmt;
19
20/// A JSON object whose entries keep the order they were given in.
21#[derive(Debug, Clone, PartialEq)]
22pub struct OrderedEntries<V>(pub Vec<(String, V)>);
23
24impl<V> OrderedEntries<V> {
25    pub fn new() -> Self {
26        Self(Vec::new())
27    }
28
29    pub fn push(&mut self, key: impl Into<String>, value: V) {
30        self.0.push((key.into(), value));
31    }
32
33    /// The first value stored under `key`.
34    pub fn get(&self, key: &str) -> Option<&V> {
35        self.0.iter().find(|(k, _)| k == key).map(|(_, v)| v)
36    }
37
38    pub fn iter(&self) -> impl Iterator<Item = (&str, &V)> {
39        self.0.iter().map(|(k, v)| (k.as_str(), v))
40    }
41
42    pub fn len(&self) -> usize {
43        self.0.len()
44    }
45
46    pub fn is_empty(&self) -> bool {
47        self.0.is_empty()
48    }
49}
50
51impl<V> Default for OrderedEntries<V> {
52    fn default() -> Self {
53        Self::new()
54    }
55}
56
57impl<V> From<Vec<(String, V)>> for OrderedEntries<V> {
58    fn from(entries: Vec<(String, V)>) -> Self {
59        Self(entries)
60    }
61}
62
63impl<K: Into<String>, V> FromIterator<(K, V)> for OrderedEntries<V> {
64    fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
65        Self(iter.into_iter().map(|(k, v)| (k.into(), v)).collect())
66    }
67}
68
69impl<V: Serialize> Serialize for OrderedEntries<V> {
70    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
71        serializer.collect_map(self.0.iter().map(|(k, v)| (k, v)))
72    }
73}
74
75impl<'de, V: Deserialize<'de>> Deserialize<'de> for OrderedEntries<V> {
76    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
77        struct EntriesVisitor<V>(std::marker::PhantomData<V>);
78
79        impl<'de, V: Deserialize<'de>> Visitor<'de> for EntriesVisitor<V> {
80            type Value = OrderedEntries<V>;
81
82            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
83                formatter.write_str("a JSON object")
84            }
85
86            fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
87                let mut entries = Vec::with_capacity(map.size_hint().unwrap_or(0));
88                while let Some(entry) = map.next_entry::<String, V>()? {
89                    entries.push(entry);
90                }
91                Ok(OrderedEntries(entries))
92            }
93        }
94
95        deserializer.deserialize_map(EntriesVisitor(std::marker::PhantomData))
96    }
97}
98
99/// What `true` and `false` mean for a noul question, when the words alone are
100/// not enough.
101#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
102pub struct SystemOneNoulCriteria {
103    #[serde(rename = "true", default, skip_serializing_if = "Option::is_none")]
104    pub when_true: Option<Value>,
105    #[serde(rename = "false", default, skip_serializing_if = "Option::is_none")]
106    pub when_false: Option<Value>,
107}
108
109/// One question about the request's state.
110#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
111#[serde(tag = "type", rename_all = "lowercase")]
112pub enum SystemOneQuestion {
113    /// A yes/no statement; answered with the probability that it is true.
114    Noul {
115        instructions: Value,
116        #[serde(default, skip_serializing_if = "Option::is_none")]
117        criteria: Option<SystemOneNoulCriteria>,
118    },
119    /// One of 2 to 255 options, numbered in the order given. Each value
120    /// describes its option (`null` for no description).
121    Choice {
122        instructions: Value,
123        criteria: OrderedEntries<Value>,
124    },
125    /// A level on an ordered scale of 2 to 10 entries, lowest first.
126    Score {
127        instructions: Value,
128        criteria: Vec<Value>,
129    },
130}
131
132impl SystemOneQuestion {
133    pub fn noul(instructions: impl Into<String>) -> Self {
134        Self::Noul {
135            instructions: Value::String(instructions.into()),
136            criteria: None,
137        }
138    }
139
140    pub fn choice<K, D>(
141        instructions: impl Into<String>,
142        options: impl IntoIterator<Item = (K, D)>,
143    ) -> Self
144    where
145        K: Into<String>,
146        D: Into<Value>,
147    {
148        Self::Choice {
149            instructions: Value::String(instructions.into()),
150            criteria: options
151                .into_iter()
152                .map(|(label, description)| (label, description.into()))
153                .collect(),
154        }
155    }
156
157    pub fn score<L: Into<Value>>(
158        instructions: impl Into<String>,
159        levels: impl IntoIterator<Item = L>,
160    ) -> Self {
161        Self::Score {
162            instructions: Value::String(instructions.into()),
163            criteria: levels.into_iter().map(Into::into).collect(),
164        }
165    }
166}
167
168/// A System One request. Up to 64 questions; see [`SystemOneQuestion`] for the
169/// per-type limits.
170#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
171pub struct SystemOneRequest {
172    /// `glm-5-3-flash` when unset. `decision-small`, `decision-medium` and
173    /// `decision-large` read text only and take at most 26 options per choice.
174    #[serde(default, skip_serializing_if = "Option::is_none")]
175    pub model: Option<String>,
176    /// Any JSON; embedded in the prompt as given.
177    pub state: Value,
178    pub questions: OrderedEntries<SystemOneQuestion>,
179    /// Up to 4 `data:` image URLs, 4 MiB each and 8 MiB in total, shown with the state
180    /// (`glm-5-3-flash` only).
181    #[serde(default, skip_serializing_if = "Vec::is_empty")]
182    pub images: Vec<String>,
183    /// Calibration temperature override; `1` returns the raw probabilities.
184    #[serde(default, skip_serializing_if = "Option::is_none")]
185    pub temperature: Option<f64>,
186}
187
188impl SystemOneRequest {
189    pub fn new(state: Value) -> Self {
190        Self {
191            model: None,
192            state,
193            questions: OrderedEntries::new(),
194            images: Vec::new(),
195            temperature: None,
196        }
197    }
198
199    pub fn with_question(mut self, name: impl Into<String>, question: SystemOneQuestion) -> Self {
200        self.questions.push(name, question);
201        self
202    }
203
204    pub fn with_model(mut self, model: impl Into<String>) -> Self {
205        self.model = Some(model.into());
206        self
207    }
208
209    pub fn with_image(mut self, data_url: impl Into<String>) -> Self {
210        self.images.push(data_url.into());
211        self
212    }
213
214    pub fn with_temperature(mut self, temperature: f64) -> Self {
215        self.temperature = Some(temperature);
216        self
217    }
218}
219
220/// The answer to one question. Every variant reports the calibration
221/// `temperature` applied and `option_mass`, the share of the model's next-token
222/// probability that fell on the offered options (low values mean the prompt did
223/// not fit the question well). The decision models report temperature 1 unless
224/// the request sets one, and an `option_mass` of 1: they score only the offered
225/// options.
226#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
227#[serde(tag = "type", rename_all = "lowercase")]
228pub enum SystemOneAnswer {
229    Noul {
230        /// Probability that the statement is true.
231        noul: f64,
232        temperature: f64,
233        option_mass: f64,
234    },
235    Choice {
236        /// The most probable option's label.
237        choice: String,
238        /// Probability per option label, in the order the options were given.
239        probabilities: OrderedEntries<f64>,
240        /// TypeSafe's choice confidence, `(p_max - 1/n) / (1 - 1/n)`: 0 when the options are
241        /// equally likely, 1 when one option takes all the probability.
242        confidence: f64,
243        temperature: f64,
244        option_mass: f64,
245    },
246    Score {
247        /// Expected level number (0-based), a probability-weighted average.
248        score: f64,
249        /// Level text keyed by level number.
250        legend: OrderedEntries<Value>,
251        /// Probability per level number.
252        probabilities: OrderedEntries<f64>,
253        /// TypeSafe's score confidence, `1 - sum(p_i |i - m|) / MAD_unif` with `m` the most
254        /// likely level: 0 when the mass is spread like a uniform distribution, 1 when it sits
255        /// on one level.
256        confidence: f64,
257        temperature: f64,
258        option_mass: f64,
259    },
260}
261
262#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
263pub struct SystemOneUsage {
264    pub input_tokens: u64,
265    pub output_tokens: u64,
266    pub cached_tokens: u64,
267    /// Upstream inference requests made: one per question on `glm-5-3-flash` (more for
268    /// wide choices), one per call on the decision models.
269    pub requests: u64,
270}
271
272#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
273pub struct SystemOneResponse {
274    pub id: String,
275    pub model: String,
276    /// One answer per question, keyed by the question's name, in question order.
277    pub answers: OrderedEntries<SystemOneAnswer>,
278    pub usage: SystemOneUsage,
279}
280
281#[cfg(test)]
282mod tests {
283    use super::*;
284    use crate::client::json_inference_request;
285    use serde_json::json;
286
287    #[test]
288    fn request_serializes_questions_and_options_in_caller_order() {
289        let request = SystemOneRequest::new(json!({"ticket": "Charged twice"}))
290            .with_question("zebra", SystemOneQuestion::noul("Is it urgent?"))
291            .with_question(
292                "intent",
293                SystemOneQuestion::choice(
294                    "What does the customer want?",
295                    [("refund", "money back"), ("10", "ten"), ("2", "two")],
296                ),
297            )
298            .with_question(
299                "frustration",
300                SystemOneQuestion::score("How frustrated?", ["Low", "High"]),
301            )
302            .with_temperature(1.0);
303
304        let encoded = serde_json::to_string(&request).unwrap();
305        assert_eq!(
306            encoded,
307            r#"{"state":{"ticket":"Charged twice"},"questions":{"zebra":{"type":"noul","instructions":"Is it urgent?"},"intent":{"type":"choice","instructions":"What does the customer want?","criteria":{"refund":"money back","10":"ten","2":"two"}},"frustration":{"type":"score","instructions":"How frustrated?","criteria":["Low","High"]}},"temperature":1.0}"#
308        );
309
310        let http =
311            json_inference_request("/v1/systemone", http::Method::POST, Some(&request)).unwrap();
312        assert_eq!(http.method(), http::Method::POST);
313        assert_eq!(http.uri(), "/v1/systemone");
314        assert_eq!(http.headers()["content-type"], "application/json");
315        assert_eq!(http.body(), encoded.as_bytes());
316    }
317
318    #[test]
319    fn noul_criteria_and_images_serialize_when_present() {
320        let request = SystemOneRequest::new(json!("state"))
321            .with_question(
322                "ok",
323                SystemOneQuestion::Noul {
324                    instructions: json!("Is it fine?"),
325                    criteria: Some(SystemOneNoulCriteria {
326                        when_true: Some(json!("all good")),
327                        when_false: None,
328                    }),
329                },
330            )
331            .with_image("data:image/png;base64,AAAA")
332            .with_model("glm-5-3-flash");
333        assert_eq!(
334            serde_json::to_value(&request).unwrap(),
335            json!({
336                "model": "glm-5-3-flash",
337                "state": "state",
338                "questions": {"ok": {"type": "noul", "instructions": "Is it fine?", "criteria": {"true": "all good"}}},
339                "images": ["data:image/png;base64,AAAA"]
340            })
341        );
342    }
343
344    #[test]
345    fn response_parses_all_three_answer_shapes_in_order() {
346        let response: SystemOneResponse = serde_json::from_str(
347            r#"{"id":"so_1","model":"glm-5-3-flash","answers":{
348                "is_urgent":{"type":"noul","noul":0.9318,"temperature":2.483,"option_mass":1.0},
349                "intent":{"type":"choice","choice":"refund","probabilities":{"refund":0.8611,"10":0.1,"2":0.0389},"confidence":0.6,"temperature":2.407,"option_mass":0.9952},
350                "frustration":{"type":"score","score":1.2,"legend":{"0":"Low","1":"High"},"probabilities":{"0":0.4,"1":0.6},"confidence":0.03,"temperature":2.48,"option_mass":0.99}
351            },"usage":{"input_tokens":388,"output_tokens":3,"cached_tokens":0,"requests":3}}"#,
352        )
353        .unwrap();
354
355        let names: Vec<&str> = response.answers.iter().map(|(name, _)| name).collect();
356        assert_eq!(names, ["is_urgent", "intent", "frustration"]);
357        match response.answers.get("intent").unwrap() {
358            SystemOneAnswer::Choice {
359                choice,
360                probabilities,
361                confidence,
362                ..
363            } => {
364                assert_eq!(choice, "refund");
365                let labels: Vec<&str> = probabilities.iter().map(|(label, _)| label).collect();
366                assert_eq!(
367                    labels,
368                    ["refund", "10", "2"],
369                    "option order survives integer-like labels"
370                );
371                assert_eq!(*confidence, 0.6);
372            }
373            other => panic!("unexpected answer {other:?}"),
374        }
375        assert!(matches!(
376            response.answers.get("is_urgent"),
377            Some(SystemOneAnswer::Noul { noul, .. }) if *noul == 0.9318
378        ));
379        assert!(matches!(
380            response.answers.get("frustration"),
381            Some(SystemOneAnswer::Score { score, legend, .. }) if *score == 1.2 && legend.get("1") == Some(&json!("High"))
382        ));
383        assert_eq!(response.usage.requests, 3);
384    }
385}