1#![forbid(unsafe_code)]
6
7use std::{collections::BTreeMap, fmt};
8
9use secrecy::{ExposeSecret, SecretString};
10use serde::{Deserialize, Serialize};
11use serde_json::Value;
12use thiserror::Error;
13
14pub const JEV_LATEST: &str = "jev-latest";
16
17pub const SYSTEM_ONE_ENDPOINT: &str = "https://api.typesafe.ai/v1/systemone";
19
20#[derive(Clone)]
22pub struct Client {
23 http: reqwest::Client,
24 api_key: SecretString,
25 endpoint: String,
26}
27
28impl Client {
29 #[must_use]
31 pub fn new(api_key: impl Into<String>) -> Self {
32 Self::with_endpoint(api_key, SYSTEM_ONE_ENDPOINT)
33 }
34
35 #[must_use]
39 pub fn with_endpoint(api_key: impl Into<String>, endpoint: impl Into<String>) -> Self {
40 Self {
41 http: reqwest::Client::new(),
42 api_key: SecretString::from(api_key.into()),
43 endpoint: endpoint.into(),
44 }
45 }
46
47 #[must_use]
49 pub fn with_http_client(mut self, http: reqwest::Client) -> Self {
50 self.http = http;
51 self
52 }
53
54 #[must_use]
56 pub fn endpoint(&self) -> &str {
57 &self.endpoint
58 }
59
60 pub async fn evaluate(&self, request: &EvaluationRequest) -> Result<EvaluationResponse, Error> {
67 let response = self
68 .http
69 .post(&self.endpoint)
70 .bearer_auth(self.api_key.expose_secret())
71 .json(request)
72 .send()
73 .await?;
74
75 let status = response.status();
76 if !status.is_success() {
77 return Err(Error::Api {
78 status: status.as_u16(),
79 body: response.text().await?,
80 });
81 }
82
83 Ok(response.json().await?)
84 }
85}
86
87impl fmt::Debug for Client {
88 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
89 formatter
90 .debug_struct("Client")
91 .field("endpoint", &self.endpoint)
92 .finish_non_exhaustive()
93 }
94}
95
96#[derive(Debug, Clone, PartialEq, Serialize)]
98pub struct EvaluationRequest {
99 pub state: Value,
101 pub model: String,
103 pub questions: BTreeMap<String, Question>,
105}
106
107impl EvaluationRequest {
108 #[must_use]
110 pub fn new(state: impl Into<Value>, questions: BTreeMap<String, Question>) -> Self {
111 Self::with_model(state, JEV_LATEST, questions)
112 }
113
114 #[must_use]
116 pub fn with_model(
117 state: impl Into<Value>,
118 model: impl Into<String>,
119 questions: BTreeMap<String, Question>,
120 ) -> Self {
121 Self {
122 state: state.into(),
123 model: model.into(),
124 questions,
125 }
126 }
127}
128
129#[derive(Debug, Clone, PartialEq, Serialize)]
131#[serde(tag = "type", rename_all = "lowercase")]
132pub enum Question {
133 Noul {
135 instructions: Value,
137 #[serde(skip_serializing_if = "Option::is_none")]
139 criteria: Option<NoulCriteria>,
140 },
141 Choice {
143 instructions: Value,
145 criteria: BTreeMap<String, Option<String>>,
147 },
148 Score {
150 instructions: Value,
152 criteria: Vec<String>,
154 },
155}
156
157impl Question {
158 #[must_use]
160 pub fn noul(instructions: impl Into<Value>) -> Self {
161 Self::Noul {
162 instructions: instructions.into(),
163 criteria: None,
164 }
165 }
166
167 #[must_use]
169 pub fn noul_with_criteria(instructions: impl Into<Value>, criteria: NoulCriteria) -> Self {
170 Self::Noul {
171 instructions: instructions.into(),
172 criteria: Some(criteria),
173 }
174 }
175
176 #[must_use]
178 pub fn choice(
179 instructions: impl Into<Value>,
180 criteria: BTreeMap<String, Option<String>>,
181 ) -> Self {
182 Self::Choice {
183 instructions: instructions.into(),
184 criteria,
185 }
186 }
187
188 #[must_use]
190 pub fn score(instructions: impl Into<Value>, criteria: Vec<String>) -> Self {
191 Self::Score {
192 instructions: instructions.into(),
193 criteria,
194 }
195 }
196}
197
198#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
200pub struct NoulCriteria {
201 #[serde(rename = "true", skip_serializing_if = "Option::is_none")]
203 pub yes: Option<String>,
204 #[serde(rename = "false", skip_serializing_if = "Option::is_none")]
206 pub no: Option<String>,
207}
208
209impl NoulCriteria {
210 #[must_use]
212 pub fn new(yes: Option<String>, no: Option<String>) -> Self {
213 Self { yes, no }
214 }
215}
216
217#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
219pub struct EvaluationResponse {
220 pub model: String,
222 pub answers: BTreeMap<String, Answer>,
224 pub usage: Usage,
226}
227
228#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
230#[serde(tag = "type", rename_all = "lowercase")]
231pub enum Answer {
232 Noul {
234 noul: f64,
236 },
237 Choice {
239 choice: String,
241 probabilities: BTreeMap<String, f64>,
243 confidence: f64,
245 },
246 Score {
248 score: f64,
250 legend: BTreeMap<String, String>,
252 probabilities: BTreeMap<String, f64>,
254 confidence: f64,
256 },
257}
258
259#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
261pub struct Usage {
262 pub input_tokens: u64,
264 pub output_tokens: u64,
266}
267
268#[derive(Debug, Error)]
270pub enum Error {
271 #[error("Jev API transport or decoding failure: {0}")]
274 Transport(#[from] reqwest::Error),
275 #[error("Jev API returned HTTP {status}: {body}")]
277 Api {
278 status: u16,
280 body: String,
282 },
283}
284
285#[cfg(test)]
286mod tests {
287 use std::collections::BTreeMap;
288
289 use serde_json::json;
290
291 use super::{Answer, EvaluationRequest, EvaluationResponse, NoulCriteria, Question};
292
293 #[test]
294 fn serializes_the_documented_request_shape() {
295 let request = EvaluationRequest::new(
296 "Help! My payouts have been failing for 3 days.",
297 BTreeMap::from([
298 (
299 "is_urgent".into(),
300 Question::noul_with_criteria(
301 "Does this convey urgency?",
302 NoulCriteria::new(
303 Some("Explicitly time-sensitive".into()),
304 Some("No urgency expressed".into()),
305 ),
306 ),
307 ),
308 (
309 "department".into(),
310 Question::choice(
311 "Which team should handle this?",
312 BTreeMap::from([
313 ("billing".into(), Some("Payments and refunds".into())),
314 ("technical".into(), None),
315 ]),
316 ),
317 ),
318 (
319 "frustration".into(),
320 Question::score(
321 "How frustrated is the customer?",
322 vec!["Calm".into(), "Frustrated".into(), "Very angry".into()],
323 ),
324 ),
325 ]),
326 );
327
328 assert_eq!(
329 serde_json::to_value(request).unwrap(),
330 json!({
331 "state": "Help! My payouts have been failing for 3 days.",
332 "model": "jev-latest",
333 "questions": {
334 "is_urgent": {
335 "type": "noul",
336 "instructions": "Does this convey urgency?",
337 "criteria": {
338 "true": "Explicitly time-sensitive",
339 "false": "No urgency expressed"
340 }
341 },
342 "department": {
343 "type": "choice",
344 "instructions": "Which team should handle this?",
345 "criteria": { "billing": "Payments and refunds", "technical": null }
346 },
347 "frustration": {
348 "type": "score",
349 "instructions": "How frustrated is the customer?",
350 "criteria": ["Calm", "Frustrated", "Very angry"]
351 }
352 }
353 })
354 );
355 }
356
357 #[test]
358 fn deserializes_all_documented_answer_types() {
359 let response: EvaluationResponse = serde_json::from_value(json!({
360 "model": "jev-latest",
361 "answers": {
362 "is_urgent": { "type": "noul", "noul": 0.92 },
363 "department": {
364 "type": "choice",
365 "choice": "technical",
366 "probabilities": { "billing": 0.08, "technical": 0.92 },
367 "confidence": 0.84
368 },
369 "frustration": {
370 "type": "score",
371 "score": 1.6,
372 "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
373 "probabilities": { "0": 0.05, "1": 0.3, "2": 0.65 },
374 "confidence": 0.78
375 }
376 },
377 "usage": { "input_tokens": 312, "output_tokens": 48 }
378 }))
379 .unwrap();
380
381 assert_eq!(response.usage.input_tokens, 312);
382 assert_eq!(response.answers["is_urgent"], Answer::Noul { noul: 0.92 });
383 assert!(matches!(
384 response.answers["department"],
385 Answer::Choice { .. }
386 ));
387 assert!(matches!(
388 response.answers["frustration"],
389 Answer::Score { .. }
390 ));
391 }
392}