1use 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#[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 #[schemars(extend("unevaluatedProperties" = false))]
40 Noul(Noul),
41 #[schemars(extend("unevaluatedProperties" = false))]
43 Choice(Choice),
44 #[schemars(extend("unevaluatedProperties" = false))]
46 Score(Score),
47}
48
49impl Question {
50 #[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 #[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 #[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#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
104#[schemars(extend("required" = ["instructions"]))]
107#[non_exhaustive]
108pub struct Noul {
109 #[serde(
114 default,
115 deserialize_with = "de::present",
116 skip_serializing_if = "Option::is_none"
117 )]
118 pub instructions: Option<Content>,
119
120 #[serde(default, skip_serializing_if = "Option::is_none")]
122 pub criteria: Option<NoulCriteria>,
123
124 #[serde(flatten)]
126 #[schemars(skip)]
127 pub extra: IndexMap<String, Value>,
128}
129
130impl Noul {
131 #[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 #[must_use]
142 pub fn with_criteria(mut self, criteria: NoulCriteria) -> Self {
143 self.criteria = Some(criteria);
144 self
145 }
146}
147
148#[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 #[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 #[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 #[serde(flatten)]
178 #[schemars(skip)]
179 pub extra: IndexMap<String, Value>,
180}
181
182impl NoulCriteria {
183 #[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#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
196#[schemars(extend("required" = ["instructions", "criteria"]))]
197#[non_exhaustive]
198pub struct Choice {
199 #[serde(
203 default,
204 deserialize_with = "de::present",
205 skip_serializing_if = "Option::is_none"
206 )]
207 pub instructions: Option<Content>,
208
209 #[serde(deserialize_with = "de::unique_map")]
214 #[schemars(extend("minProperties" = 1, "maxProperties" = MAX_CHOICE_OPTIONS))]
215 pub criteria: IndexMap<String, Content>,
216
217 #[serde(flatten)]
219 #[schemars(skip)]
220 pub extra: IndexMap<String, Value>,
221}
222
223impl Choice {
224 #[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 #[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 #[must_use]
242 pub fn bare_option(self, name: impl Into<String>) -> Self {
243 self.option(name, Content::null())
244 }
245}
246
247#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
249#[schemars(extend("required" = ["instructions", "criteria"]))]
250#[non_exhaustive]
251pub struct Score {
252 #[serde(
256 default,
257 deserialize_with = "de::present",
258 skip_serializing_if = "Option::is_none"
259 )]
260 pub instructions: Option<Content>,
261
262 #[schemars(schema_with = "levels_schema")]
266 pub criteria: Vec<Content>,
267
268 #[serde(flatten)]
270 #[schemars(skip)]
271 pub extra: IndexMap<String, Value>,
272}
273
274impl Score {
275 #[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 #[must_use]
286 pub fn level(mut self, description: impl Into<Content>) -> Self {
287 self.criteria.push(description.into());
288 self
289 }
290}
291
292fn 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}