Skip to main content

jev_client/
lib.rs

1//! Unofficial Rust client for [TypeSafe AI](https://typesafe.ai)'s **Jev** model.
2//!
3//! Jev is a "System One" model: it never generates text. A request carries a `state` plus a map
4//! of typed questions (`noul`, `choice`, `score`) and the response carries calibrated
5//! probabilities over answers the caller defined.
6//!
7//! This crate is the library half of the [`jev` command-line tool]. It owns the typed request and
8//! answer model, offline validation, the HTTP transport with retries, and typed errors. It
9//! deliberately knows nothing about command-line parsing, terminals or configuration files, so it
10//! can be used on its own as a Rust client.
11//!
12//! # The typed model
13//!
14//! [`Request`] holds a `state` and a map of [`Question`]s ([`Noul`], [`Choice`], [`Score`]);
15//! [`Response`] holds one [`Answer`] per question plus [`Usage`]. `state`, `instructions` and
16//! criteria values are free-form [`Content`]. [`ModelList`] is the body of `GET /v1/models`, and
17//! [`pricing`] turns usage into an estimated cost.
18//!
19//! ```
20//! use jev_client::{Noul, Request, Response, pricing};
21//!
22//! let request = Request::new("Help! My payouts have been failing for 3 days.", "jev-latest")
23//!     .question("is_urgent", Noul::new("Does this convey urgency?"));
24//! assert!(serde_json::to_string(&request).unwrap().contains(r#""type":"noul""#));
25//!
26//! let response: Response = serde_json::from_str(
27//!     r#"{
28//!         "model": "jev-1.13.0",
29//!         "answers": { "is_urgent": { "type": "noul", "noul": 0.92 } },
30//!         "usage": { "input_tokens": 312, "output_tokens": 48 }
31//!     }"#,
32//! )
33//! .unwrap();
34//!
35//! let is_urgent = response.answers.get("is_urgent").and_then(|answer| answer.as_noul());
36//! assert_eq!(is_urgent.map(|answer| answer.noul), Some(0.92));
37//! assert!(pricing::estimate_cost_usd(&response.model, response.usage).is_some());
38//! ```
39//!
40//! Three properties hold across these types:
41//!
42//! - **Requests are sent as written.** Key order is preserved, an explicit `null` stays distinct
43//!   from an absent key, and fields this crate does not know are kept and passed through. They are
44//!   kept rather than dropped because the API silently accepts an unknown field inside a question,
45//!   so offline validation needs to see a misspelt `criteria` to report it.
46//! - **Responses parse tolerantly.** Unknown fields are ignored, and an answer of an unknown type
47//!   (or a known type whose shape has changed) is kept as raw JSON in [`Answer::Unknown`] instead
48//!   of failing the whole response.
49//! - **One definition, many uses.** Every type derives [`schemars::JsonSchema`], so the JSON
50//!   Schemas handed to editors, AI agents and MCP clients cannot drift from what is parsed.
51//!
52//! # Talking to the API
53//!
54//! [`Transport`] is the seam: `evaluate` and `list_models`, each returning a [`Reply`] with the
55//! parsed body plus the request id, latency and attempt count. [`HttpTransport`] is the real one.
56//! Code that needs the API should depend on the trait, so its tests can use an in-memory fake.
57//!
58//! - **Credentials.** [`ApiKey`] wipes itself on drop and never prints. [`BaseUrl`] insists on
59//!   `https://` (plain HTTP only for loopback, or by explicit opt-in), and redirects are not
60//!   followed, so the key cannot be sent somewhere unexpected.
61//! - **Retries.** [`RetryPolicy`] defaults to the official SDKs' behaviour: 2 retries with jittered
62//!   exponential backoff for 408, 429, 5xx, timeouts and connection failures, honouring
63//!   `Retry-After`. 400, 401, 403, 404 and 422 are never retried. [`Clock`] keeps tests instant.
64//!   A [`Throttle`] shared by concurrent calls makes a 429 or 529 on one of them slow all of them.
65//! - **Errors.** One [`Error`] with an [`ErrorKind`] mirroring the SDKs' error classes, carrying
66//!   the HTTP status, the API's `error_type`, and the `x-typesafe-request-id`. No error ever
67//!   contains the API key or a request's `state`.
68//! - **Logging.** `tracing` events at `DEBUG` cover method, URL, status, timing, request id and
69//!   retry decisions. Bodies are traced only on explicit opt-in, and `Authorization` never is.
70//!
71//! The types describe shapes only. Limits such as 255 choice options or 2 to 10 score levels are
72//! enforced by [`validate`], which checks a request offline and reports every problem at once, each
73//! with the question it is in, a path, a stable rule id and a suggested fix.
74//!
75//! This project is not affiliated with, endorsed by, or sponsored by TypeSafe AI.
76//!
77//! [`jev` command-line tool]: https://github.com/shaharia-lab/jev-cli
78#![forbid(unsafe_code)]
79
80mod answer;
81mod base_url;
82mod clock;
83mod content;
84mod de;
85mod error;
86#[cfg(any(test, fuzzing))]
87#[doc(hidden)]
88pub mod fuzz;
89mod http;
90mod models;
91pub mod pricing;
92mod question;
93mod request;
94mod response;
95mod retry;
96mod secret;
97mod throttle;
98mod transport;
99pub mod validate;
100
101pub use answer::{Answer, ChoiceAnswer, NoulAnswer, ScoreAnswer};
102pub use base_url::{BaseUrl, InvalidBaseUrl};
103pub use clock::{Clock, SystemClock};
104pub use content::Content;
105pub use error::{Error, ErrorKind};
106pub use http::{HttpTransport, HttpTransportBuilder};
107pub use models::{ModelCard, ModelList};
108pub use question::{Choice, Noul, NoulCriteria, Question, Score};
109pub use request::Request;
110pub use response::{Response, Usage};
111pub use retry::RetryPolicy;
112pub use secret::{ApiKey, InvalidApiKey};
113pub use throttle::Throttle;
114pub use transport::{Reply, ReplyMeta, Transport};
115
116/// Version of this crate, as published.
117///
118/// The command-line tool reports it, and the HTTP transport will send it in the `User-Agent`.
119pub const VERSION: &str = env!("CARGO_PKG_VERSION");
120
121#[cfg(test)]
122mod tests {
123    use super::VERSION;
124
125    #[test]
126    fn version_is_a_semver_triple() {
127        let core = VERSION.split(['-', '+']).next().unwrap();
128        let parts: Vec<&str> = core.split('.').collect();
129
130        assert_eq!(parts.len(), 3, "expected MAJOR.MINOR.PATCH, got {VERSION}");
131        for part in parts {
132            part.parse::<u64>()
133                .unwrap_or_else(|_| panic!("non-numeric component in {VERSION}"));
134        }
135    }
136}