Skip to main content

typesafe_ai/
request.rs

1use std::collections::BTreeMap;
2
3use serde::{Deserialize, Serialize};
4use serde_json::Value;
5
6use crate::Error;
7
8const DEFAULT_MODEL: &str = "jev-latest";
9
10/// State and typed questions sent to the System One evaluation endpoint.
11#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
12pub struct Request {
13    /// State for the model to evaluate.
14    ///
15    /// The top-level value must be a string, object, or array.
16    pub state: Value,
17    /// Model identifier. Defaults to `jev-latest`.
18    pub model: String,
19    /// Questions keyed by caller-selected identifiers.
20    ///
21    /// An identifier correlates its question with the returned answer; it is not used for
22    /// inference.
23    pub questions: BTreeMap<String, Question>,
24}
25
26impl Request {
27    /// Creates a request using `jev-latest` and no questions.
28    pub fn new(state: impl Into<Value>) -> Self {
29        Self {
30            state: state.into(),
31            model: DEFAULT_MODEL.to_owned(),
32            questions: BTreeMap::new(),
33        }
34    }
35
36    /// Sets the model identifier.
37    #[must_use]
38    pub fn with_model(mut self, model: impl Into<String>) -> Self {
39        self.model = model.into();
40        self
41    }
42
43    /// Adds a question and returns the request.
44    ///
45    /// A later question with the same ID replaces the earlier one.
46    #[must_use]
47    pub fn with_question(mut self, id: impl Into<String>, question: Question) -> Self {
48        self.questions.insert(id.into(), question);
49        self
50    }
51
52    /// Inserts a question, returning a previous question with the same id.
53    pub fn insert_question(
54        &mut self,
55        id: impl Into<String>,
56        question: Question,
57    ) -> Option<Question> {
58        self.questions.insert(id.into(), question)
59    }
60
61    /// Validates the request against documented API shape constraints.
62    ///
63    /// Clients call this before sending a request. It is also available for applications
64    /// that want to validate earlier.
65    pub fn validate(&self) -> Result<(), Error> {
66        if !is_state(&self.state) {
67            return Err(Error::Validation {
68                field: "state".to_owned(),
69                message: "must be a string, object, or array".to_owned(),
70            });
71        }
72
73        for (id, question) in &self.questions {
74            question.validate(id)?;
75        }
76        Ok(())
77    }
78}
79
80impl Default for Request {
81    fn default() -> Self {
82        Self::new(Value::String(String::new()))
83    }
84}
85
86/// Criteria defining the positive and negative sides of a Noul question.
87///
88/// Each side accepts a string, object, array, or JSON null.
89#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
90pub struct NoulCriteria {
91    /// Description of what a positive answer means, or null when unspecified.
92    #[serde(default, rename = "true")]
93    pub when_true: Value,
94    /// Description of what a negative answer means, or null when unspecified.
95    #[serde(default, rename = "false")]
96    pub when_false: Value,
97}
98
99impl NoulCriteria {
100    /// Creates positive and negative Noul criteria.
101    pub fn new(when_true: impl Into<Value>, when_false: impl Into<Value>) -> Self {
102        Self {
103            when_true: when_true.into(),
104            when_false: when_false.into(),
105        }
106    }
107}
108
109/// A typed judgment for System One to make against request state.
110///
111/// Instructions and criteria descriptions accept strings, objects, arrays, or JSON null.
112#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
113#[serde(tag = "type", rename_all = "lowercase")]
114pub enum Question {
115    /// A yes/no judgment returned as the probability of yes.
116    Noul {
117        /// The judgment the model should make.
118        instructions: Value,
119        /// Optional descriptions of the positive and negative answers.
120        #[serde(skip_serializing_if = "Option::is_none")]
121        criteria: Option<NoulCriteria>,
122    },
123    /// Selection of one label from a caller-defined set.
124    Choice {
125        /// The decision the model should make.
126        instructions: Value,
127        /// Options keyed by their labels.
128        criteria: BTreeMap<String, Value>,
129    },
130    /// A rating along an ordered caller-defined rubric.
131    Score {
132        /// The rating the model should make.
133        instructions: Value,
134        /// Ordered descriptions of the score levels.
135        criteria: Vec<Value>,
136    },
137}
138
139impl Question {
140    /// Creates a Noul question without explicit yes and no criteria.
141    pub fn noul(instructions: impl Into<Value>) -> Self {
142        Self::Noul {
143            instructions: instructions.into(),
144            criteria: None,
145        }
146    }
147
148    /// Creates a Noul question with explicit positive and negative criteria.
149    pub fn noul_with_criteria(instructions: impl Into<Value>, criteria: NoulCriteria) -> Self {
150        Self::Noul {
151            instructions: instructions.into(),
152            criteria: Some(criteria),
153        }
154    }
155
156    /// Creates a Choice question from options keyed by their returned labels.
157    ///
158    /// At least one option is required when the request is validated.
159    pub fn choice(instructions: impl Into<Value>, criteria: BTreeMap<String, Value>) -> Self {
160        Self::Choice {
161            instructions: instructions.into(),
162            criteria,
163        }
164    }
165
166    /// Creates a Score question from ordered level descriptions.
167    ///
168    /// At least two levels are required when the request is validated.
169    pub fn score(instructions: impl Into<Value>, criteria: Vec<Value>) -> Self {
170        Self::Score {
171            instructions: instructions.into(),
172            criteria,
173        }
174    }
175
176    fn validate(&self, id: &str) -> Result<(), Error> {
177        let instructions = match self {
178            Self::Noul { instructions, .. }
179            | Self::Choice { instructions, .. }
180            | Self::Score { instructions, .. } => instructions,
181        };
182        validate_entry(instructions, format!("questions.{id}.instructions"))?;
183
184        match self {
185            Self::Noul {
186                criteria: Some(criteria),
187                ..
188            } => {
189                validate_entry(&criteria.when_true, format!("questions.{id}.criteria.true"))?;
190                validate_entry(
191                    &criteria.when_false,
192                    format!("questions.{id}.criteria.false"),
193                )
194            }
195            Self::Noul { criteria: None, .. } => Ok(()),
196            Self::Choice { criteria, .. } => {
197                if criteria.is_empty() {
198                    return Err(Error::Validation {
199                        field: format!("questions.{id}.criteria"),
200                        message: "must contain at least one option".to_owned(),
201                    });
202                }
203                for (option, description) in criteria {
204                    validate_entry(description, format!("questions.{id}.criteria.{option}"))?;
205                }
206                Ok(())
207            }
208            Self::Score { criteria, .. } => {
209                if criteria.len() < 2 {
210                    return Err(Error::Validation {
211                        field: format!("questions.{id}.criteria"),
212                        message: "must contain at least two levels".to_owned(),
213                    });
214                }
215                for (level, description) in criteria.iter().enumerate() {
216                    validate_entry(description, format!("questions.{id}.criteria[{level}]"))?;
217                }
218                Ok(())
219            }
220        }
221    }
222}
223
224fn is_state(value: &Value) -> bool {
225    matches!(value, Value::String(_) | Value::Object(_) | Value::Array(_))
226}
227
228fn validate_entry(value: &Value, field: String) -> Result<(), Error> {
229    if matches!(
230        value,
231        Value::String(_) | Value::Object(_) | Value::Array(_) | Value::Null
232    ) {
233        Ok(())
234    } else {
235        Err(Error::Validation {
236            field,
237            message: "must be a string, object, array, or null".to_owned(),
238        })
239    }
240}