jev/cases.rs
1//! Predefined "cases" — a state plus one or more questions, loaded from YAML/JSON
2//! configuration instead of assembled in code.
3//!
4//! A [`CaseSet`] is the config-file counterpart of [`Questions::builder`]: where the
5//! dynamic path builds one [`Questions`] value per call in Rust, a case set is a whole
6//! batch of named `(state, questions)` pairs — for example a fixture file of support
7//! tickets with the questions to ask about each — deserialized once and replayed
8//! through [`crate::Client::run_case`] (one call) or [`crate::run_cases`] (many, bounded
9//! concurrency).
10//!
11//! # File format
12//!
13//! ```yaml
14//! version: 1
15//! cases:
16//! - id: ticket-001
17//! state: "Customer wants a refund for a duplicate charge."
18//! questions:
19//! refund:
20//! type: noul
21//! instructions: "Is the customer asking for money back?"
22//! team:
23//! type: choice
24//! instructions: "Which team should own this ticket?"
25//! criteria:
26//! payments: "Checkout, billing, or payment processing issues."
27//! frontend: "Rendering, layout, or browser compatibility issues."
28//! - id: ticket-002
29//! name: "Login outage report"
30//! state:
31//! subject: "Login broken"
32//! body: "Cannot log in after the last release."
33//! questions:
34//! urgency:
35//! type: score
36//! instructions: "How urgent is this?"
37//! criteria: ["Can wait", "This week", "Blocking revenue"]
38//! ```
39//!
40//! `state` accepts the same `string | object | array` shapes as [`crate::State`];
41//! each question accepts the same `type`-tagged shapes as [`crate::Question`] (`noul`
42//! with optional `criteria.true`/`criteria.false`, `choice` with a `criteria` map,
43//! `score` with a `criteria` list), keyed by question key, in file order. Loading a
44//! `CaseSet` (via [`CaseSet::from_json_str`], [`CaseSet::from_yaml_str`], or
45//! [`CaseSet::from_file`]) validates every case's questions eagerly through
46//! [`Questions::builder`]'s checks — key charset, guidance length, option/level counts
47//! — so a malformed fixture fails at load time, not mid-batch.
48//!
49//! # Examples
50//!
51//! ```
52//! use jev::CaseSet;
53//!
54//! let json = r#"{
55//! "cases": [{
56//! "id": "ticket-001",
57//! "state": "Customer wants a refund for a duplicate charge.",
58//! "questions": {
59//! "refund": {
60//! "type": "noul",
61//! "instructions": "Is the customer asking for money back?"
62//! }
63//! }
64//! }]
65//! }"#;
66//! let cases = CaseSet::from_json_str(json).unwrap();
67//! assert_eq!(cases.len(), 1);
68//! assert_eq!(cases.iter().next().unwrap().id, "ticket-001");
69//! ```
70
71use std::collections::HashSet;
72
73use indexmap::IndexMap;
74use serde::Deserialize;
75
76use crate::{
77 error::Error,
78 guidance::Guidance,
79 question::{Questions, QuestionsBuilder},
80 state::State,
81 wire::Response,
82};
83
84/// Minimum number of cases in one [`CaseSet`].
85pub const MIN_CASES: usize = 1;
86/// Maximum number of cases in one [`CaseSet`].
87pub const MAX_CASES: usize = 10_000;
88/// Maximum length, in bytes, of a case's `id` or `name`.
89pub const MAX_CASE_ID_BYTES: usize = 256;
90
91/// One configured question inside a [`Case`]: the same `noul`/`choice`/`score` shape
92/// [`crate::Question`] sends on the wire, deserialized from a case file instead of
93/// built through [`QuestionsBuilder`].
94#[derive(Debug, Clone, PartialEq, Deserialize)]
95#[serde(tag = "type", rename_all = "snake_case")]
96pub enum CaseQuestion {
97 /// A yes/no question. See [`crate::Question::Noul`].
98 Noul {
99 /// What to ask the model.
100 instructions: Guidance,
101 /// Optional per-branch criteria clarifying what counts as "true" or "false".
102 #[serde(default)]
103 criteria: Option<CaseNoulCriteria>,
104 },
105 /// A single-select question over a fixed, ordered option set. See
106 /// [`crate::Question::Choice`].
107 Choice {
108 /// What to ask the model.
109 instructions: Guidance,
110 /// Wire key -> criteria, in declaration order.
111 criteria: IndexMap<String, Guidance>,
112 },
113 /// A question that places the state on an ordered scale. See
114 /// [`crate::Question::Score`].
115 Score {
116 /// What to ask the model.
117 instructions: Guidance,
118 /// One criterion per level, lowest first.
119 criteria: Vec<Guidance>,
120 },
121}
122
123/// The `"true"`/`"false"` criteria pair for a [`CaseQuestion::Noul`].
124#[derive(Debug, Clone, PartialEq, Deserialize)]
125pub struct CaseNoulCriteria {
126 /// Criterion describing what counts as "yes".
127 #[serde(rename = "true")]
128 pub r#true: Guidance,
129 /// Criterion describing what counts as "no".
130 #[serde(rename = "false")]
131 pub r#false: Guidance,
132}
133
134/// One predefined case: one state, one or more questions, one API call.
135///
136/// Construct these by deserializing a [`CaseSet`], which validates `questions` eagerly
137/// via [`Case::build_questions`]; there is no public unchecked constructor.
138#[derive(Debug, Clone, PartialEq, Deserialize)]
139pub struct Case {
140 /// Caller-defined identifier for this case, echoed back on [`CaseResult`] for log
141 /// correlation and report keying.
142 pub id: String,
143 /// Optional human-readable label, distinct from `id` (dashboards, reports).
144 #[serde(default)]
145 pub name: Option<String>,
146 /// The state this case's questions are evaluated against.
147 pub state: State,
148 /// Question key -> question, in file order.
149 pub questions: IndexMap<String, CaseQuestion>,
150}
151
152impl Case {
153 /// Converts this case's `questions` into a validated [`Questions`], running the
154 /// same checks [`QuestionsBuilder::build`] applies to the hand-written path.
155 ///
156 /// This does not itself validate `id`/`name`; [`CaseSet::from_json_str`] and
157 /// friends do so for every case as part of loading the whole file.
158 ///
159 /// # Errors
160 ///
161 /// [`Error::Invalid`] on the first invariant violated: question count,
162 /// duplicate/invalid keys, guidance length, or option/level counts.
163 pub fn build_questions(&self) -> Result<Questions, Error> {
164 let mut builder = Questions::builder();
165 for (key, question) in &self.questions {
166 builder = push_question(builder, key, question);
167 }
168 builder.build()
169 }
170}
171
172/// Appends one [`CaseQuestion`] to a [`QuestionsBuilder`] under `key`.
173fn push_question(
174 builder: QuestionsBuilder,
175 key: &str,
176 question: &CaseQuestion,
177) -> QuestionsBuilder {
178 match question {
179 CaseQuestion::Noul {
180 instructions,
181 criteria: None,
182 } => builder.noul(key, instructions.clone()),
183 CaseQuestion::Noul {
184 instructions,
185 criteria: Some(criteria),
186 } => builder.noul_with(
187 key,
188 instructions.clone(),
189 criteria.r#true.clone(),
190 criteria.r#false.clone(),
191 ),
192 CaseQuestion::Choice {
193 instructions,
194 criteria,
195 } => builder.choice(
196 key,
197 instructions.clone(),
198 criteria.iter().map(|(k, v)| (k.clone(), v.clone())),
199 ),
200 CaseQuestion::Score {
201 instructions,
202 criteria,
203 } => builder.score(key, instructions.clone(), criteria.clone()),
204 }
205}
206
207/// A batch of [`Case`]s loaded from one YAML/JSON document: the config-file
208/// counterpart of hand-assembling many [`Questions`] values in code.
209///
210/// See the module-level docs for the file format.
211#[derive(Debug, Clone, PartialEq, Deserialize)]
212#[serde(rename_all = "camelCase", deny_unknown_fields)]
213pub struct CaseSet {
214 /// Format version of this file, for callers that need to evolve the schema. Not
215 /// otherwise interpreted by this SDK.
216 #[serde(default)]
217 pub version: Option<u32>,
218 /// The cases, in file order.
219 pub cases: Vec<Case>,
220}
221
222impl CaseSet {
223 /// Parses a `CaseSet` from a JSON document.
224 ///
225 /// # Errors
226 ///
227 /// [`Error::Parse`] if `json` is not valid JSON; [`Error::Invalid`] if it parses
228 /// but fails case-set validation (see the module-level docs).
229 pub fn from_json_str(json: &str) -> Result<Self, Error> {
230 let case_set: CaseSet =
231 serde_json::from_str(json).map_err(|e| Error::Parse(e.to_string()))?;
232 validate(case_set)
233 }
234
235 /// Parses a `CaseSet` from an already-parsed JSON value.
236 ///
237 /// # Errors
238 ///
239 /// [`Error::Parse`] if `value` does not match the case-set schema; [`Error::Invalid`]
240 /// if it parses but fails case-set validation.
241 pub fn from_json_value(value: serde_json::Value) -> Result<Self, Error> {
242 let case_set: CaseSet =
243 serde_json::from_value(value).map_err(|e| Error::Parse(e.to_string()))?;
244 validate(case_set)
245 }
246
247 /// Parses a `CaseSet` from a YAML document.
248 ///
249 /// # Errors
250 ///
251 /// [`Error::Parse`] if `yaml` is not valid YAML; [`Error::Invalid`] if it parses
252 /// but fails case-set validation.
253 #[cfg(feature = "yaml")]
254 pub fn from_yaml_str(yaml: &str) -> Result<Self, Error> {
255 let case_set: CaseSet =
256 serde_norway::from_str(yaml).map_err(|e| Error::Parse(e.to_string()))?;
257 validate(case_set)
258 }
259
260 /// Loads a `CaseSet` from a file, choosing the JSON or YAML parser by extension
261 /// (`.json` vs. `.yaml`/`.yml`).
262 ///
263 /// Reads the file with `tokio::fs`, not `std::fs`, so it never blocks the async
264 /// runtime's worker thread.
265 ///
266 /// # Errors
267 ///
268 /// [`Error::Io`] if the file cannot be read; [`Error::Invalid`] if the extension is
269 /// missing, unrecognized, or names a YAML file while the `yaml` feature is
270 /// disabled, or if the parsed content fails case-set validation; [`Error::Parse`]
271 /// if the content is not well-formed JSON/YAML.
272 pub async fn from_file(path: impl AsRef<std::path::Path>) -> Result<Self, Error> {
273 let path = path.as_ref();
274 let extension = path.extension().and_then(std::ffi::OsStr::to_str);
275 // Resolve which parser to use, or the `Invalid` rejection, before touching the
276 // filesystem: an unrecognized extension is a caller programming error, not an
277 // I/O condition, and should not depend on whether the (wrong) file happens to
278 // exist.
279 let parser = match extension {
280 Some("json") => Self::from_json_str,
281 #[cfg(feature = "yaml")]
282 Some("yaml" | "yml") => Self::from_yaml_str,
283 #[cfg(not(feature = "yaml"))]
284 Some("yaml" | "yml") => {
285 return Err(Error::Invalid {
286 field: "path".to_string(),
287 reason: format!(
288 "{} is a YAML file but the `yaml` feature is disabled",
289 path.display()
290 ),
291 });
292 }
293 _ => {
294 return Err(Error::Invalid {
295 field: "path".to_string(),
296 reason: format!(
297 "unrecognized case file extension {extension:?}; expected json, yaml, or \
298 yml"
299 ),
300 });
301 }
302 };
303
304 let contents = tokio::fs::read_to_string(path).await?;
305 parser(&contents)
306 }
307
308 /// The number of cases.
309 #[must_use]
310 pub fn len(&self) -> usize {
311 self.cases.len()
312 }
313
314 /// Whether there are no cases.
315 ///
316 /// Never `true` for a successfully loaded `CaseSet`: loading rejects an empty
317 /// `cases` list. Provided for API symmetry with
318 /// [`Vec::is_empty`] and to satisfy `clippy::len_without_is_empty`.
319 #[must_use]
320 pub fn is_empty(&self) -> bool {
321 self.cases.is_empty()
322 }
323
324 /// Iterates cases in file order.
325 pub fn iter(&self) -> std::slice::Iter<'_, Case> {
326 self.cases.iter()
327 }
328
329 /// Borrows the cases as a slice, for [`crate::run_cases`].
330 #[must_use]
331 pub fn as_slice(&self) -> &[Case] {
332 &self.cases
333 }
334}
335
336impl<'a> IntoIterator for &'a CaseSet {
337 type Item = &'a Case;
338 type IntoIter = std::slice::Iter<'a, Case>;
339
340 fn into_iter(self) -> Self::IntoIter {
341 self.cases.iter()
342 }
343}
344
345/// Validates a freshly deserialized `CaseSet`: case count, `id`/`name` bounds, `id`
346/// uniqueness, and (via [`Case::build_questions`]) every case's question schema.
347fn validate(case_set: CaseSet) -> Result<CaseSet, Error> {
348 let count = case_set.cases.len();
349 if !(MIN_CASES..=MAX_CASES).contains(&count) {
350 return Err(Error::Invalid {
351 field: "cases".to_string(),
352 reason: format!("expected {MIN_CASES}..={MAX_CASES} cases, got {count}"),
353 });
354 }
355
356 let mut seen_ids: HashSet<&str> = HashSet::with_capacity(count);
357 for case in &case_set.cases {
358 validate_id_field("case.id", &case.id)?;
359 if let Some(name) = &case.name {
360 validate_id_field("case.name", name)?;
361 }
362 if !seen_ids.insert(case.id.as_str()) {
363 return Err(Error::Invalid {
364 field: "cases".to_string(),
365 reason: format!("duplicate case id `{}`", case.id),
366 });
367 }
368 case.build_questions()?;
369 }
370
371 Ok(case_set)
372}
373
374/// Validates that a case's `id` or `name` is non-empty and within
375/// [`MAX_CASE_ID_BYTES`].
376fn validate_id_field(field: &str, value: &str) -> Result<(), Error> {
377 if value.is_empty() || value.len() > MAX_CASE_ID_BYTES {
378 return Err(Error::Invalid {
379 field: field.to_string(),
380 reason: format!(
381 "length must be 1..={MAX_CASE_ID_BYTES} bytes, got {}",
382 value.len()
383 ),
384 });
385 }
386 Ok(())
387}
388
389/// The result of running one [`Case`] through [`crate::Client::run_case`]: the case's
390/// `id` alongside the raw [`Response`].
391#[derive(Debug)]
392pub struct CaseResult {
393 /// The case's `id`, for correlating this result back to its source case.
394 pub id: String,
395 /// The server's response: answers, usage, and identifiers.
396 pub response: Response,
397}
398
399#[cfg(test)]
400mod tests {
401 use serde_json::json;
402
403 use super::*;
404
405 #[test]
406 fn test_should_parse_minimal_case_set_from_json() {
407 let cases = CaseSet::from_json_value(json!({
408 "cases": [{
409 "id": "t1",
410 "state": "hello",
411 "questions": {
412 "flag": {"type": "noul", "instructions": "Is this flagged?"}
413 }
414 }]
415 }))
416 .unwrap();
417 assert_eq!(cases.len(), 1);
418 let case = cases.iter().next().unwrap();
419 assert_eq!(case.id, "t1");
420 assert_eq!(case.state, State::Text("hello".to_string()));
421 assert_eq!(case.build_questions().unwrap().len(), 1);
422 }
423
424 #[test]
425 fn test_should_parse_case_with_structured_state_and_all_primitives() {
426 let cases = CaseSet::from_json_value(json!({
427 "cases": [{
428 "id": "t1",
429 "state": {"subject": "billing"},
430 "questions": {
431 "refund": {"type": "noul", "instructions": "Refund?",
432 "criteria": {"true": "Yes text.", "false": "No text."}},
433 "team": {"type": "choice", "instructions": "Which team?",
434 "criteria": {"a": "A.", "b": "B."}},
435 "urgency": {"type": "score", "instructions": "How urgent?",
436 "criteria": ["Low", "High"]}
437 }
438 }]
439 }))
440 .unwrap();
441 let case = &cases.iter().next().unwrap();
442 let questions = case.build_questions().unwrap();
443 assert_eq!(questions.len(), 3);
444 }
445
446 #[test]
447 fn test_should_reject_empty_case_list() {
448 let err = CaseSet::from_json_value(json!({"cases": []})).unwrap_err();
449 assert!(matches!(err, Error::Invalid { .. }));
450 }
451
452 #[test]
453 fn test_should_reject_duplicate_case_ids() {
454 let err = CaseSet::from_json_value(json!({
455 "cases": [
456 {"id": "dup", "state": "a", "questions": {"q": {"type": "noul", "instructions": "Q?"}}},
457 {"id": "dup", "state": "b", "questions": {"q": {"type": "noul", "instructions": "Q?"}}}
458 ]
459 }))
460 .unwrap_err();
461 assert!(matches!(err, Error::Invalid { .. }));
462 }
463
464 #[test]
465 fn test_should_reject_empty_case_id() {
466 let err = CaseSet::from_json_value(json!({
467 "cases": [{"id": "", "state": "a", "questions": {"q": {"type": "noul", "instructions": "Q?"}}}]
468 }))
469 .unwrap_err();
470 assert!(matches!(err, Error::Invalid { .. }));
471 }
472
473 #[test]
474 fn test_should_reject_case_with_invalid_question_schema() {
475 // Question key uses an uppercase letter, invalid per `Questions::builder`'s charset.
476 let err = CaseSet::from_json_value(json!({
477 "cases": [{"id": "t1", "state": "a", "questions": {"Q": {"type": "noul", "instructions": "Q?"}}}]
478 }))
479 .unwrap_err();
480 assert!(matches!(err, Error::Invalid { .. }));
481 }
482
483 #[test]
484 fn test_should_reject_unknown_top_level_field() {
485 let err = serde_json::from_value::<CaseSet>(json!({
486 "cases": [],
487 "bogus": true
488 }))
489 .unwrap_err();
490 assert!(!err.to_string().is_empty());
491 }
492
493 #[tokio::test]
494 async fn test_should_reject_json_naming_unsupported_extension() {
495 let err = CaseSet::from_file("cases.toml").await.unwrap_err();
496 assert!(matches!(err, Error::Invalid { .. }));
497 }
498
499 #[tokio::test]
500 async fn test_should_return_io_error_for_missing_file() {
501 let err = CaseSet::from_file("/no/such/path/cases.json")
502 .await
503 .unwrap_err();
504 assert!(matches!(err, Error::Io(_)));
505 }
506
507 #[cfg(feature = "yaml")]
508 #[test]
509 fn test_should_parse_case_set_from_yaml() {
510 let yaml = r"
511cases:
512 - id: t1
513 state: hello
514 questions:
515 flag:
516 type: noul
517 instructions: Is this flagged?
518";
519 let cases = CaseSet::from_yaml_str(yaml).unwrap();
520 assert_eq!(cases.len(), 1);
521 }
522}