Skip to main content

jev_client/
request.rs

1//! The body of `POST /v1/systemone`.
2
3use indexmap::IndexMap;
4use schemars::JsonSchema;
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7
8use crate::content::{Content, non_null_schema};
9use crate::de;
10use crate::question::Question;
11
12/// An evaluation request: one `state`, judged by every question independently and in parallel.
13///
14/// ```
15/// use jev_client::{Choice, Noul, Request};
16///
17/// let request = Request::new("Help! My payouts have been failing for 3 days.", "jev-latest")
18///     .question("is_urgent", Noul::new("Does this convey urgency?"))
19///     .question(
20///         "department",
21///         Choice::new("Which team should handle this?")
22///             .option("billing", "Payments, invoicing, refunds")
23///             .option("technical", "Bugs, outages, integrations")
24///             .bare_option("other"),
25///     );
26///
27/// assert_eq!(request.questions.len(), 2);
28/// ```
29#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
30#[schemars(
31    description = "An evaluation request: one `state`, judged by every question independently and in parallel.",
32    extend("additionalProperties" = false)
33)]
34#[non_exhaustive]
35pub struct Request {
36    /// The content to evaluate: a string, or structured data such as a chat log or a record.
37    ///
38    /// The API rejects `null` and scalar values here.
39    #[schemars(schema_with = "non_null_schema")]
40    pub state: Content,
41
42    /// The model that handles the request: an alias such as `jev-latest`, or a versioned id such
43    /// as `jev-1.13.0`. Aliases move without notice; pin a versioned id once thresholds are tuned.
44    pub model: String,
45
46    /// The questions, keyed by an id the caller chooses. Answers come back under the same ids.
47    ///
48    /// Questions keep the order they were written in. Ids are never sent to the model. A repeated
49    /// id is a parse error when reading JSON or YAML text directly (a parser that has already
50    /// collapsed the document into a generic value keeps only the last one).
51    #[serde(deserialize_with = "de::unique_map")]
52    #[schemars(extend("minProperties" = 1))]
53    pub questions: IndexMap<String, Question>,
54
55    /// Top-level fields this version of the crate does not know, sent to the API unchanged.
56    ///
57    /// The API currently rejects any unknown top-level field with an uninformative
58    /// `400 Invalid request.`, so validation reports these before a request is spent.
59    #[serde(flatten)]
60    #[schemars(skip)]
61    pub extra: IndexMap<String, Value>,
62}
63
64impl Request {
65    /// A request for `model` over `state`, with no questions yet.
66    #[must_use]
67    pub fn new(state: impl Into<Content>, model: impl Into<String>) -> Self {
68        Self {
69            state: state.into(),
70            model: model.into(),
71            questions: IndexMap::new(),
72            extra: IndexMap::new(),
73        }
74    }
75
76    /// Adds a question under `id`, replacing any question already using that id.
77    #[must_use]
78    pub fn question(mut self, id: impl Into<String>, question: impl Into<Question>) -> Self {
79        self.questions.insert(id.into(), question.into());
80        self
81    }
82}
83
84#[cfg(test)]
85mod tests {
86    use serde_json::json;
87
88    use super::Request;
89    use crate::{Noul, Question};
90
91    #[test]
92    fn questions_keep_the_order_they_were_written_in() {
93        let text = r#"{"state":"s","model":"jev-latest","questions":{"z":{"type":"noul","instructions":"?"},"a":{"type":"noul","instructions":"?"}}}"#;
94
95        let request: Request = serde_json::from_str(text).unwrap();
96
97        assert_eq!(request.questions.keys().collect::<Vec<_>>(), ["z", "a"]);
98        assert_eq!(serde_json::to_string(&request).unwrap(), text);
99    }
100
101    #[test]
102    fn a_repeated_question_id_is_a_parse_error() {
103        let text = r#"{"state":"s","model":"m","questions":{"q":{"type":"noul","instructions":"a"},"q":{"type":"noul","instructions":"b"}}}"#;
104
105        let error = serde_json::from_str::<Request>(text)
106            .unwrap_err()
107            .to_string();
108
109        assert!(error.contains("duplicate key `q`"), "{error}");
110    }
111
112    #[test]
113    fn the_builder_replaces_a_question_that_reuses_an_id() {
114        let request = Request::new("s", "m")
115            .question("q", Noul::new("first"))
116            .question("q", Noul::new("second"));
117
118        assert_eq!(request.questions.len(), 1);
119        assert_eq!(
120            request.questions.get("q"),
121            Some(&Question::from(Noul::new("second")))
122        );
123    }
124
125    #[test]
126    fn unknown_top_level_fields_are_kept() {
127        let json = json!({ "state": ["a"], "model": "m", "questions": {}, "temperature": 0 });
128
129        let request: Request = serde_json::from_value(json.clone()).unwrap();
130
131        assert_eq!(request.extra.get("temperature"), Some(&json!(0)));
132        assert_eq!(serde_json::to_value(&request).unwrap(), json);
133    }
134
135    #[test]
136    fn required_fields_are_required() {
137        let error = serde_json::from_value::<Request>(json!({ "state": "s", "questions": {} }));
138
139        assert!(
140            error
141                .unwrap_err()
142                .to_string()
143                .contains("missing field `model`")
144        );
145    }
146}