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    /// Defaults to the only supported model, `glm-5-3-flash`.
173    #[serde(default, skip_serializing_if = "Option::is_none")]
174    pub model: Option<String>,
175    /// Any JSON; embedded in the prompt as given.
176    pub state: Value,
177    pub questions: OrderedEntries<SystemOneQuestion>,
178    /// Up to 4 `data:` image URLs, 4 MiB each and 8 MiB in total, shown with the state.
179    #[serde(default, skip_serializing_if = "Vec::is_empty")]
180    pub images: Vec<String>,
181    /// Calibration temperature override; `1` returns the raw probabilities.
182    #[serde(default, skip_serializing_if = "Option::is_none")]
183    pub temperature: Option<f64>,
184}
185
186impl SystemOneRequest {
187    pub fn new(state: Value) -> Self {
188        Self {
189            model: None,
190            state,
191            questions: OrderedEntries::new(),
192            images: Vec::new(),
193            temperature: None,
194        }
195    }
196
197    pub fn with_question(mut self, name: impl Into<String>, question: SystemOneQuestion) -> Self {
198        self.questions.push(name, question);
199        self
200    }
201
202    pub fn with_model(mut self, model: impl Into<String>) -> Self {
203        self.model = Some(model.into());
204        self
205    }
206
207    pub fn with_image(mut self, data_url: impl Into<String>) -> Self {
208        self.images.push(data_url.into());
209        self
210    }
211
212    pub fn with_temperature(mut self, temperature: f64) -> Self {
213        self.temperature = Some(temperature);
214        self
215    }
216}
217
218/// The answer to one question. Every variant reports the calibration
219/// `temperature` applied and `option_mass`, the share of the model's next-token
220/// probability that fell on the offered options (low values mean the prompt did
221/// not fit the question well).
222#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
223#[serde(tag = "type", rename_all = "lowercase")]
224pub enum SystemOneAnswer {
225    Noul {
226        /// Probability that the statement is true.
227        noul: f64,
228        temperature: f64,
229        option_mass: f64,
230    },
231    Choice {
232        /// The most probable option's label.
233        choice: String,
234        /// Probability per option label, in the order the options were given.
235        probabilities: OrderedEntries<f64>,
236        /// Peakedness of the distribution, from 0 (uniform) to 1 (certain).
237        confidence: f64,
238        temperature: f64,
239        option_mass: f64,
240    },
241    Score {
242        /// Expected level number (0-based), a probability-weighted average.
243        score: f64,
244        /// Level text keyed by level number.
245        legend: OrderedEntries<Value>,
246        /// Probability per level number.
247        probabilities: OrderedEntries<f64>,
248        confidence: f64,
249        temperature: f64,
250        option_mass: f64,
251    },
252}
253
254#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
255pub struct SystemOneUsage {
256    pub input_tokens: u64,
257    pub output_tokens: u64,
258    pub cached_tokens: u64,
259    /// Upstream inference requests made: one per question, more for wide choices.
260    pub requests: u64,
261}
262
263#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
264pub struct SystemOneResponse {
265    pub id: String,
266    pub model: String,
267    /// One answer per question, keyed by the question's name, in question order.
268    pub answers: OrderedEntries<SystemOneAnswer>,
269    pub usage: SystemOneUsage,
270}
271
272#[cfg(test)]
273mod tests {
274    use super::*;
275    use crate::client::json_inference_request;
276    use serde_json::json;
277
278    #[test]
279    fn request_serializes_questions_and_options_in_caller_order() {
280        let request = SystemOneRequest::new(json!({"ticket": "Charged twice"}))
281            .with_question("zebra", SystemOneQuestion::noul("Is it urgent?"))
282            .with_question(
283                "intent",
284                SystemOneQuestion::choice(
285                    "What does the customer want?",
286                    [("refund", "money back"), ("10", "ten"), ("2", "two")],
287                ),
288            )
289            .with_question(
290                "frustration",
291                SystemOneQuestion::score("How frustrated?", ["Low", "High"]),
292            )
293            .with_temperature(1.0);
294
295        let encoded = serde_json::to_string(&request).unwrap();
296        assert_eq!(
297            encoded,
298            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}"#
299        );
300
301        let http =
302            json_inference_request("/v1/systemone", http::Method::POST, Some(&request)).unwrap();
303        assert_eq!(http.method(), http::Method::POST);
304        assert_eq!(http.uri(), "/v1/systemone");
305        assert_eq!(http.headers()["content-type"], "application/json");
306        assert_eq!(http.body(), encoded.as_bytes());
307    }
308
309    #[test]
310    fn noul_criteria_and_images_serialize_when_present() {
311        let request = SystemOneRequest::new(json!("state"))
312            .with_question(
313                "ok",
314                SystemOneQuestion::Noul {
315                    instructions: json!("Is it fine?"),
316                    criteria: Some(SystemOneNoulCriteria {
317                        when_true: Some(json!("all good")),
318                        when_false: None,
319                    }),
320                },
321            )
322            .with_image("data:image/png;base64,AAAA")
323            .with_model("glm-5-3-flash");
324        assert_eq!(
325            serde_json::to_value(&request).unwrap(),
326            json!({
327                "model": "glm-5-3-flash",
328                "state": "state",
329                "questions": {"ok": {"type": "noul", "instructions": "Is it fine?", "criteria": {"true": "all good"}}},
330                "images": ["data:image/png;base64,AAAA"]
331            })
332        );
333    }
334
335    #[test]
336    fn response_parses_all_three_answer_shapes_in_order() {
337        let response: SystemOneResponse = serde_json::from_str(
338            r#"{"id":"so_1","model":"glm-5-3-flash","answers":{
339                "is_urgent":{"type":"noul","noul":0.9318,"temperature":2.483,"option_mass":1.0},
340                "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},
341                "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}
342            },"usage":{"input_tokens":388,"output_tokens":3,"cached_tokens":0,"requests":3}}"#,
343        )
344        .unwrap();
345
346        let names: Vec<&str> = response.answers.iter().map(|(name, _)| name).collect();
347        assert_eq!(names, ["is_urgent", "intent", "frustration"]);
348        match response.answers.get("intent").unwrap() {
349            SystemOneAnswer::Choice {
350                choice,
351                probabilities,
352                confidence,
353                ..
354            } => {
355                assert_eq!(choice, "refund");
356                let labels: Vec<&str> = probabilities.iter().map(|(label, _)| label).collect();
357                assert_eq!(
358                    labels,
359                    ["refund", "10", "2"],
360                    "option order survives integer-like labels"
361                );
362                assert_eq!(*confidence, 0.6);
363            }
364            other => panic!("unexpected answer {other:?}"),
365        }
366        assert!(matches!(
367            response.answers.get("is_urgent"),
368            Some(SystemOneAnswer::Noul { noul, .. }) if *noul == 0.9318
369        ));
370        assert!(matches!(
371            response.answers.get("frustration"),
372            Some(SystemOneAnswer::Score { score, legend, .. }) if *score == 1.2 && legend.get("1") == Some(&json!("High"))
373        ));
374        assert_eq!(response.usage.requests, 3);
375    }
376}