Skip to main content

typesafe_ai_client/
lib.rs

1//! Typed Rust bindings for `TypeSafe` AI's Jev System One HTTP API.
2//!
3//! See the [API reference](https://docs.typesafe.ai/api) for the service contract.
4
5#![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
14/// The Jev model alias recommended by the `TypeSafe` API reference.
15pub const JEV_LATEST: &str = "jev-latest";
16
17/// The official Jev System One evaluation endpoint.
18pub const SYSTEM_ONE_ENDPOINT: &str = "https://api.typesafe.ai/v1/systemone";
19
20/// A typed client for the Jev System One evaluation endpoint.
21#[derive(Clone)]
22pub struct Client {
23    http: reqwest::Client,
24    api_key: SecretString,
25    endpoint: String,
26}
27
28impl Client {
29    /// Creates a client that targets `TypeSafe` AI's official System One endpoint.
30    #[must_use]
31    pub fn new(api_key: impl Into<String>) -> Self {
32        Self::with_endpoint(api_key, SYSTEM_ONE_ENDPOINT)
33    }
34
35    /// Creates a client for an explicit System One endpoint.
36    ///
37    /// This is primarily useful for tests, proxies, and compatible private deployments.
38    #[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    /// Replaces the underlying HTTP client, for example to set a timeout or proxy.
48    #[must_use]
49    pub fn with_http_client(mut self, http: reqwest::Client) -> Self {
50        self.http = http;
51        self
52    }
53
54    /// Returns the endpoint used for evaluations.
55    #[must_use]
56    pub fn endpoint(&self) -> &str {
57        &self.endpoint
58    }
59
60    /// Evaluates a state against the request's typed questions.
61    ///
62    /// # Errors
63    ///
64    /// Returns [`Error::Transport`] when the request cannot be sent or the success
65    /// payload cannot be decoded, and [`Error::Api`] for a non-success response.
66    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/// A System One request, including the state to evaluate and named questions.
97#[derive(Debug, Clone, PartialEq, Serialize)]
98pub struct EvaluationRequest {
99    /// Text or structured JSON state to evaluate.
100    pub state: Value,
101    /// The Jev model alias or version to use.
102    pub model: String,
103    /// Typed questions keyed by caller-owned question IDs.
104    pub questions: BTreeMap<String, Question>,
105}
106
107impl EvaluationRequest {
108    /// Creates a request using the recommended `jev-latest` model alias.
109    #[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    /// Creates a request with an explicit Jev model identifier.
115    #[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/// A typed Jev question.
130#[derive(Debug, Clone, PartialEq, Serialize)]
131#[serde(tag = "type", rename_all = "lowercase")]
132pub enum Question {
133    /// A yes/no judgment represented as a probability from zero to one.
134    Noul {
135        /// The yes/no judgment to make against the state.
136        instructions: Value,
137        /// Optional descriptions of what yes and no mean.
138        #[serde(skip_serializing_if = "Option::is_none")]
139        criteria: Option<NoulCriteria>,
140    },
141    /// A selection among caller-defined named options.
142    Choice {
143        /// The selection to make against the state.
144        instructions: Value,
145        /// Options and their optional rubric descriptions.
146        criteria: BTreeMap<String, Option<String>>,
147    },
148    /// A probability-weighted position in an ordered caller-defined rubric.
149    Score {
150        /// The rating to make against the state.
151        instructions: Value,
152        /// Ordered descriptions of each score level.
153        criteria: Vec<String>,
154    },
155}
156
157impl Question {
158    /// Creates a yes/no question without additional criteria.
159    #[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    /// Adds explicit descriptions for the yes and no outcomes of a Noul question.
168    #[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    /// Creates a choice question.
177    #[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    /// Creates a score question.
189    #[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/// Optional semantic descriptions of Noul's true and false outcomes.
199#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
200pub struct NoulCriteria {
201    /// Description of a result near one.
202    #[serde(rename = "true", skip_serializing_if = "Option::is_none")]
203    pub yes: Option<String>,
204    /// Description of a result near zero.
205    #[serde(rename = "false", skip_serializing_if = "Option::is_none")]
206    pub no: Option<String>,
207}
208
209impl NoulCriteria {
210    /// Creates criteria with independent optional descriptions for yes and no.
211    #[must_use]
212    pub fn new(yes: Option<String>, no: Option<String>) -> Self {
213        Self { yes, no }
214    }
215}
216
217/// A successful System One evaluation.
218#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
219pub struct EvaluationResponse {
220    /// The model that performed the evaluation.
221    pub model: String,
222    /// One typed answer for each requested question ID.
223    pub answers: BTreeMap<String, Answer>,
224    /// Input and output token accounting for this evaluation.
225    pub usage: Usage,
226}
227
228/// One typed answer returned by Jev.
229#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
230#[serde(tag = "type", rename_all = "lowercase")]
231pub enum Answer {
232    /// A yes/no answer represented as the probability of yes.
233    Noul {
234        /// Probability from zero (no) to one (yes).
235        noul: f64,
236    },
237    /// The highest-probability choice and its distribution.
238    Choice {
239        /// The selected option.
240        choice: String,
241        /// Probability for each caller-defined option.
242        probabilities: BTreeMap<String, f64>,
243        /// Concentration-derived certainty of the distribution.
244        confidence: f64,
245    },
246    /// A probability-weighted score and its distribution.
247    Score {
248        /// Probability-weighted position across the score levels.
249        score: f64,
250        /// Mapping from score level to its caller-provided description.
251        legend: BTreeMap<String, String>,
252        /// Probability assigned to each score level.
253        probabilities: BTreeMap<String, f64>,
254        /// Concentration-derived certainty of the distribution.
255        confidence: f64,
256    },
257}
258
259/// Token usage reported by the API.
260#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
261pub struct Usage {
262    /// Number of input tokens consumed.
263    pub input_tokens: u64,
264    /// Number of output tokens consumed.
265    pub output_tokens: u64,
266}
267
268/// Failures returned while calling the Jev API.
269#[derive(Debug, Error)]
270pub enum Error {
271    /// The request could not be sent, the response body could not be read, or a
272    /// successful response did not match the documented JSON contract.
273    #[error("Jev API transport or decoding failure: {0}")]
274    Transport(#[from] reqwest::Error),
275    /// The API returned a non-success HTTP status and its response body.
276    #[error("Jev API returned HTTP {status}: {body}")]
277    Api {
278        /// HTTP status code from the API.
279        status: u16,
280        /// Unmodified response body supplied by the API.
281        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}