Skip to main content

jev_client/
question.rs

1//! Typed questions: [`Noul`], [`Choice`] and [`Score`].
2
3use indexmap::IndexMap;
4use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7
8use crate::content::{Content, non_null_schema};
9use crate::de;
10use crate::validate::{MAX_CHOICE_OPTIONS, MAX_SCORE_LEVELS, MIN_SCORE_LEVELS};
11
12/// One typed question. The `type` field selects the variant.
13///
14/// A question's id (its key in [`Request::questions`](crate::Request::questions)) is never sent
15/// to the model, so the full meaning belongs in `instructions`.
16///
17/// ```
18/// use jev_client::{Noul, Question};
19///
20/// let question = Question::from(Noul::new("Does this convey urgency?"));
21/// assert_eq!(
22///     serde_json::to_string(&question).unwrap(),
23///     r#"{"type":"noul","instructions":"Does this convey urgency?"}"#
24/// );
25/// ```
26// The schemas are stricter than the parser on purpose. Parsing keeps unknown fields so validation
27// can report them; the schema is the authoring contract, so it rejects them outright and an editor
28// or an agent sees a misspelt `criteria` immediately. `unevaluatedProperties` is used on the
29// variants, rather than `additionalProperties` on the structs, because it sees through the `$ref`
30// that sits beside the `type` tag.
31#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
32#[serde(tag = "type", rename_all = "lowercase")]
33#[schemars(
34    description = "One typed question. The `type` field selects the kind: `noul`, `choice` or `score`. The question id is never sent to the model, so put the full meaning in `instructions`."
35)]
36#[non_exhaustive]
37pub enum Question {
38    /// A yes/no question, answered with the probability of yes.
39    #[schemars(extend("unevaluatedProperties" = false))]
40    Noul(Noul),
41    /// Pick one option from a set, answered with a probability per option.
42    #[schemars(extend("unevaluatedProperties" = false))]
43    Choice(Choice),
44    /// Rate along an ordered rubric, answered with a probability per level.
45    #[schemars(extend("unevaluatedProperties" = false))]
46    Score(Score),
47}
48
49impl Question {
50    /// The wire name of the question type: `noul`, `choice` or `score`.
51    #[must_use]
52    pub const fn type_name(&self) -> &'static str {
53        match self {
54            Self::Noul(_) => "noul",
55            Self::Choice(_) => "choice",
56            Self::Score(_) => "score",
57        }
58    }
59
60    /// The question's instructions, when it has any.
61    #[must_use]
62    pub const fn instructions(&self) -> Option<&Content> {
63        match self {
64            Self::Noul(question) => question.instructions.as_ref(),
65            Self::Choice(question) => question.instructions.as_ref(),
66            Self::Score(question) => question.instructions.as_ref(),
67        }
68    }
69
70    /// Fields this version of the crate does not know, as written by the caller.
71    ///
72    /// The API silently accepts unknown fields inside a question, so a misspelt `criteria` would
73    /// otherwise go unnoticed. Validation reads this to report them.
74    #[must_use]
75    pub const fn extra(&self) -> &IndexMap<String, Value> {
76        match self {
77            Self::Noul(question) => &question.extra,
78            Self::Choice(question) => &question.extra,
79            Self::Score(question) => &question.extra,
80        }
81    }
82}
83
84impl From<Noul> for Question {
85    fn from(question: Noul) -> Self {
86        Self::Noul(question)
87    }
88}
89
90impl From<Choice> for Question {
91    fn from(question: Choice) -> Self {
92        Self::Choice(question)
93    }
94}
95
96impl From<Score> for Question {
97    fn from(question: Score) -> Self {
98        Self::Score(question)
99    }
100}
101
102/// A yes/no question. The answer is the probability that the answer is yes.
103#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
104// `instructions` has a serde default so that validation, not parsing, reports its absence. The
105// schema still requires it, as the API reference does.
106#[schemars(extend("required" = ["instructions"]))]
107#[non_exhaustive]
108pub struct Noul {
109    /// The yes/no question to evaluate.
110    ///
111    /// The API reference marks this as required. In practice the server also accepts a Noul that
112    /// has only `criteria`, so it is optional here and offline validation decides.
113    #[serde(
114        default,
115        deserialize_with = "de::present",
116        skip_serializing_if = "Option::is_none"
117    )]
118    pub instructions: Option<Content>,
119
120    /// Optional descriptions of what a yes and a no mean.
121    #[serde(default, skip_serializing_if = "Option::is_none")]
122    pub criteria: Option<NoulCriteria>,
123
124    /// Fields this version of the crate does not know, sent to the API unchanged.
125    #[serde(flatten)]
126    #[schemars(skip)]
127    pub extra: IndexMap<String, Value>,
128}
129
130impl Noul {
131    /// A Noul with the given instructions and no criteria.
132    #[must_use]
133    pub fn new(instructions: impl Into<Content>) -> Self {
134        Self {
135            instructions: Some(instructions.into()),
136            ..Self::default()
137        }
138    }
139
140    /// Sets what a yes and a no mean.
141    #[must_use]
142    pub fn with_criteria(mut self, criteria: NoulCriteria) -> Self {
143        self.criteria = Some(criteria);
144        self
145    }
146}
147
148/// What a yes and a no mean for a [`Noul`]. Either side may be omitted.
149#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
150#[schemars(
151    description = "What a yes and a no mean for a noul. Either side may be omitted.",
152    extend("additionalProperties" = false)
153)]
154#[non_exhaustive]
155pub struct NoulCriteria {
156    /// What a yes (a value near 1) means.
157    #[serde(
158        rename = "true",
159        default,
160        deserialize_with = "de::present",
161        skip_serializing_if = "Option::is_none"
162    )]
163    pub when_true: Option<Content>,
164
165    /// What a no (a value near 0) means.
166    #[serde(
167        rename = "false",
168        default,
169        deserialize_with = "de::present",
170        skip_serializing_if = "Option::is_none"
171    )]
172    pub when_false: Option<Content>,
173
174    /// Keys other than `true` and `false`, sent to the API unchanged.
175    ///
176    /// The API accepts them without complaint; validation reports them.
177    #[serde(flatten)]
178    #[schemars(skip)]
179    pub extra: IndexMap<String, Value>,
180}
181
182impl NoulCriteria {
183    /// Criteria describing both sides of the question.
184    #[must_use]
185    pub fn new(when_true: impl Into<Content>, when_false: impl Into<Content>) -> Self {
186        Self {
187            when_true: Some(when_true.into()),
188            when_false: Some(when_false.into()),
189            extra: IndexMap::new(),
190        }
191    }
192}
193
194/// Picks one option from a set the caller defines.
195#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
196#[schemars(extend("required" = ["instructions", "criteria"]))]
197#[non_exhaustive]
198pub struct Choice {
199    /// What the model should decide.
200    ///
201    /// Marked required by the API reference, although the server accepts a Choice without it.
202    #[serde(
203        default,
204        deserialize_with = "de::present",
205        skip_serializing_if = "Option::is_none"
206    )]
207    pub instructions: Option<Content>,
208
209    /// Each option mapped to its description, or to `null` when the name says enough.
210    ///
211    /// Options keep the order they were written in. The API allows up to 255 of them. A repeated
212    /// option is a parse error when reading JSON or YAML text directly.
213    #[serde(deserialize_with = "de::unique_map")]
214    #[schemars(extend("minProperties" = 1, "maxProperties" = MAX_CHOICE_OPTIONS))]
215    pub criteria: IndexMap<String, Content>,
216
217    /// Fields this version of the crate does not know, sent to the API unchanged.
218    #[serde(flatten)]
219    #[schemars(skip)]
220    pub extra: IndexMap<String, Value>,
221}
222
223impl Choice {
224    /// A Choice with the given instructions and no options yet.
225    #[must_use]
226    pub fn new(instructions: impl Into<Content>) -> Self {
227        Self {
228            instructions: Some(instructions.into()),
229            ..Self::default()
230        }
231    }
232
233    /// Adds an option with a description, replacing any option already using that name.
234    #[must_use]
235    pub fn option(mut self, name: impl Into<String>, description: impl Into<Content>) -> Self {
236        self.criteria.insert(name.into(), description.into());
237        self
238    }
239
240    /// Adds an option whose name needs no description (sent as `null`).
241    #[must_use]
242    pub fn bare_option(self, name: impl Into<String>) -> Self {
243        self.option(name, Content::null())
244    }
245}
246
247/// Rates the state along an ordered rubric. A level's number is its index in `criteria`.
248#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
249#[schemars(extend("required" = ["instructions", "criteria"]))]
250#[non_exhaustive]
251pub struct Score {
252    /// What the model should rate.
253    ///
254    /// Marked required by the API reference, although the server accepts a Score without it.
255    #[serde(
256        default,
257        deserialize_with = "de::present",
258        skip_serializing_if = "Option::is_none"
259    )]
260    pub instructions: Option<Content>,
261
262    /// Level descriptions in order, from level 0 upwards. The API allows 2 to 10 levels.
263    ///
264    /// Unlike a choice option, a level cannot be `null`: the server rejects it with a 422.
265    #[schemars(schema_with = "levels_schema")]
266    pub criteria: Vec<Content>,
267
268    /// Fields this version of the crate does not know, sent to the API unchanged.
269    #[serde(flatten)]
270    #[schemars(skip)]
271    pub extra: IndexMap<String, Value>,
272}
273
274impl Score {
275    /// A Score with the given instructions and no levels yet.
276    #[must_use]
277    pub fn new(instructions: impl Into<Content>) -> Self {
278        Self {
279            instructions: Some(instructions.into()),
280            ..Self::default()
281        }
282    }
283
284    /// Appends the next level of the rubric.
285    #[must_use]
286    pub fn level(mut self, description: impl Into<Content>) -> Self {
287        self.criteria.push(description.into());
288        self
289    }
290}
291
292/// Schema for [`Score::criteria`]: an array whose entries may not be `null`.
293fn levels_schema(generator: &mut SchemaGenerator) -> Schema {
294    json_schema!({
295        "type": "array",
296        "items": non_null_schema(generator),
297        "minItems": MIN_SCORE_LEVELS,
298        "maxItems": MAX_SCORE_LEVELS
299    })
300}
301
302#[cfg(test)]
303mod tests {
304    use serde_json::{Value, json};
305
306    use super::{Choice, Noul, NoulCriteria, Question, Score};
307    use crate::Content;
308
309    fn round_trip(json: &Value) -> Value {
310        let question: Question = serde_json::from_value(json.clone()).unwrap();
311        serde_json::to_value(&question).unwrap()
312    }
313
314    #[test]
315    fn builders_produce_the_documented_wire_shape() {
316        let noul = Noul::new("Does this convey urgency?").with_criteria(NoulCriteria::new(
317            "Explicitly time-sensitive",
318            "No urgency expressed",
319        ));
320        let choice = Choice::new("Which team should handle this?")
321            .option("billing", "Payments, invoicing, refunds")
322            .bare_option("other");
323        let score = Score::new("How frustrated is the customer?")
324            .level("Calm")
325            .level("Angry");
326
327        assert_eq!(
328            serde_json::to_value(Question::from(noul)).unwrap(),
329            json!({
330                "type": "noul",
331                "instructions": "Does this convey urgency?",
332                "criteria": { "true": "Explicitly time-sensitive", "false": "No urgency expressed" }
333            })
334        );
335        assert_eq!(
336            serde_json::to_value(Question::from(choice)).unwrap(),
337            json!({
338                "type": "choice",
339                "instructions": "Which team should handle this?",
340                "criteria": { "billing": "Payments, invoicing, refunds", "other": null }
341            })
342        );
343        assert_eq!(
344            serde_json::to_value(Question::from(score)).unwrap(),
345            json!({
346                "type": "score",
347                "instructions": "How frustrated is the customer?",
348                "criteria": ["Calm", "Angry"]
349            })
350        );
351    }
352
353    #[test]
354    fn structured_instructions_and_criteria_round_trip() {
355        let json = json!({
356            "type": "score",
357            "instructions": { "question": "How risky is this change?", "focus": ["scope"] },
358            "criteria": ["Safe", { "what": "Risky", "signals": ["touches billing"] }, ["Dangerous"]]
359        });
360
361        assert_eq!(round_trip(&json), json);
362    }
363
364    #[test]
365    fn an_explicit_null_is_kept_distinct_from_an_absent_key() {
366        let explicit =
367            json!({ "type": "noul", "instructions": null, "criteria": { "true": null } });
368        let absent = json!({ "type": "noul", "criteria": {} });
369
370        assert_eq!(round_trip(&explicit), explicit);
371        assert_eq!(round_trip(&absent), absent);
372
373        let Question::Noul(noul) = serde_json::from_value(explicit).unwrap() else {
374            panic!("expected a noul");
375        };
376        assert_eq!(noul.instructions, Some(Content::null()));
377        let criteria = noul.criteria.unwrap();
378        assert_eq!(criteria.when_true, Some(Content::null()));
379        assert_eq!(criteria.when_false, None);
380    }
381
382    #[test]
383    fn choice_options_keep_the_order_they_were_written_in() {
384        let text = r#"{"type":"choice","instructions":"?","criteria":{"zebra":null,"apple":"a","mango":null}}"#;
385        let question: Question = serde_json::from_str(text).unwrap();
386
387        let Question::Choice(choice) = &question else {
388            panic!("expected a choice")
389        };
390        assert_eq!(
391            choice.criteria.keys().collect::<Vec<_>>(),
392            ["zebra", "apple", "mango"]
393        );
394        assert_eq!(serde_json::to_string(&question).unwrap(), text);
395    }
396
397    #[test]
398    fn a_repeated_choice_option_is_a_parse_error() {
399        let text =
400            r#"{"type":"choice","instructions":"?","criteria":{"a":null,"b":null,"a":"again"}}"#;
401
402        let error = serde_json::from_str::<Question>(text)
403            .unwrap_err()
404            .to_string();
405
406        assert!(error.contains("duplicate key `a`"), "{error}");
407    }
408
409    #[test]
410    fn unknown_fields_are_kept_for_validation_and_sent_unchanged() {
411        let json = json!({
412            "type": "noul",
413            "instructions": "Is it urgent?",
414            "critera": { "true": "typo in the key above" },
415            "criteria": { "true": "yes", "maybe": "not a real side" }
416        });
417
418        let question: Question = serde_json::from_value(json.clone()).unwrap();
419
420        assert_eq!(question.extra().keys().collect::<Vec<_>>(), ["critera"]);
421        let Question::Noul(noul) = &question else {
422            panic!("expected a noul")
423        };
424        assert_eq!(
425            noul.criteria
426                .as_ref()
427                .unwrap()
428                .extra
429                .keys()
430                .collect::<Vec<_>>(),
431            ["maybe"]
432        );
433        assert_eq!(serde_json::to_value(&question).unwrap(), json);
434    }
435
436    #[test]
437    fn a_missing_or_unknown_type_is_rejected() {
438        let missing = serde_json::from_value::<Question>(json!({ "instructions": "?" }));
439        let unknown = serde_json::from_value::<Question>(json!({ "type": "rank" }));
440
441        assert!(
442            missing
443                .unwrap_err()
444                .to_string()
445                .contains("missing field `type`")
446        );
447        assert!(
448            unknown
449                .unwrap_err()
450                .to_string()
451                .contains("unknown variant `rank`")
452        );
453    }
454
455    #[test]
456    fn accessors_report_the_type_and_instructions() {
457        let question = Question::from(Score::new("Rate it").level("low").level("high"));
458
459        assert_eq!(question.type_name(), "score");
460        assert_eq!(
461            question.instructions().and_then(Content::as_str),
462            Some("Rate it")
463        );
464        assert!(question.extra().is_empty());
465    }
466}