Expand description
Unofficial Rust client for TypeSafe AI’s Jev model.
Jev is a “System One” model: it never generates text. A request carries a state plus a map
of typed questions (noul, choice, score) and the response carries calibrated
probabilities over answers the caller defined.
This crate is the library half of the jev command-line tool. It owns the typed request and
answer model, offline validation, the HTTP transport with retries, and typed errors. It
deliberately knows nothing about command-line parsing, terminals or configuration files, so it
can be used on its own as a Rust client.
§The typed model
Request holds a state and a map of Questions (Noul, Choice, Score);
Response holds one Answer per question plus Usage. state, instructions and
criteria values are free-form Content. ModelList is the body of GET /v1/models, and
pricing turns usage into an estimated cost.
use jev_client::{Noul, Request, Response, pricing};
let request = Request::new("Help! My payouts have been failing for 3 days.", "jev-latest")
.question("is_urgent", Noul::new("Does this convey urgency?"));
assert!(serde_json::to_string(&request).unwrap().contains(r#""type":"noul""#));
let response: Response = serde_json::from_str(
r#"{
"model": "jev-1.13.0",
"answers": { "is_urgent": { "type": "noul", "noul": 0.92 } },
"usage": { "input_tokens": 312, "output_tokens": 48 }
}"#,
)
.unwrap();
let is_urgent = response.answers.get("is_urgent").and_then(|answer| answer.as_noul());
assert_eq!(is_urgent.map(|answer| answer.noul), Some(0.92));
assert!(pricing::estimate_cost_usd(&response.model, response.usage).is_some());Three properties hold across these types:
- Requests are sent as written. Key order is preserved, an explicit
nullstays distinct from an absent key, and fields this crate does not know are kept and passed through. They are kept rather than dropped because the API silently accepts an unknown field inside a question, so offline validation needs to see a misspeltcriteriato report it. - Responses parse tolerantly. Unknown fields are ignored, and an answer of an unknown type
(or a known type whose shape has changed) is kept as raw JSON in
Answer::Unknowninstead of failing the whole response. - One definition, many uses. Every type derives
schemars::JsonSchema, so the JSON Schemas handed to editors, AI agents and MCP clients cannot drift from what is parsed.
§Talking to the API
Transport is the seam: evaluate and list_models, each returning a Reply with the
parsed body plus the request id, latency and attempt count. HttpTransport is the real one.
Code that needs the API should depend on the trait, so its tests can use an in-memory fake.
- Credentials.
ApiKeywipes itself on drop and never prints.BaseUrlinsists onhttps://(plain HTTP only for loopback, or by explicit opt-in), and redirects are not followed, so the key cannot be sent somewhere unexpected. - Retries.
RetryPolicydefaults to the official SDKs’ behaviour: 2 retries with jittered exponential backoff for 408, 429, 5xx, timeouts and connection failures, honouringRetry-After. 400, 401, 403, 404 and 422 are never retried.Clockkeeps tests instant. AThrottleshared by concurrent calls makes a 429 or 529 on one of them slow all of them. - Errors. One
Errorwith anErrorKindmirroring the SDKs’ error classes, carrying the HTTP status, the API’serror_type, and thex-typesafe-request-id. No error ever contains the API key or a request’sstate. - Logging.
tracingevents atDEBUGcover method, URL, status, timing, request id and retry decisions. Bodies are traced only on explicit opt-in, andAuthorizationnever is.
The types describe shapes only. Limits such as 255 choice options or 2 to 10 score levels are
enforced by validate, which checks a request offline and reports every problem at once, each
with the question it is in, a path, a stable rule id and a suggested fix.
This project is not affiliated with, endorsed by, or sponsored by TypeSafe AI.
Modules§
- pricing
- Built-in prices, and cost estimates derived from token usage.
- validate
- Offline validation of a request, before any money is spent on it.
Structs§
- ApiKey
- A TypeSafe API key.
- BaseUrl
- The root URL of the TypeSafe API, such as
https://api.typesafe.ai. - Choice
- Picks one option from a set the caller defines.
- Choice
Answer - The answer to a
Choice. - Content
- Free-form JSON that Jev reads as content: a string, an object, an array, or
null. - Error
- An error from a
Transport. - Http
Transport - A
Transportthat talks to the TypeSafe API over HTTPS. - Http
Transport Builder - Configures and builds an
HttpTransport. - Model
Card - One model or alias, as listed by the API.
- Model
List - The model names an account can send in a request’s
modelfield. - Noul
- A yes/no question. The answer is the probability that the answer is yes.
- Noul
Answer - The answer to a
Noul. It has noconfidence: the probability is the signal. - Noul
Criteria - What a yes and a no mean for a
Noul. Either side may be omitted. - Reply
- A successful answer from the API: the parsed body, and facts about the exchange.
- Reply
Meta - Facts about one exchange with the API.
- Request
- An evaluation request: one
state, judged by every question independently and in parallel. - Response
- An evaluation response: one answer per question, under the ids the request used.
- Retry
Policy - How failed requests are retried.
- Score
- Rates the state along an ordered rubric. A level’s number is its index in
criteria. - Score
Answer - The answer to a
Score. - System
Clock - The real clock. Sleeping uses the Tokio timer, so it must run inside a Tokio runtime.
- Throttle
- Pacing shared by every call through the transports that hold it.
- Usage
- Token usage for one request. Only input tokens are billed.
Enums§
- Answer
- The answer to one question. The
typefield mirrors the question’s type. - Error
Kind - What went wrong, as a category a caller can act on.
- Invalid
ApiKey - Why a string was rejected as an API key. The message never contains the key.
- Invalid
Base Url - Why a string was rejected as a base URL.
- Question
- One typed question. The
typefield selects the variant.
Constants§
- VERSION
- Version of this crate, as published.