Skip to main content

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}