Skip to main content

Crate jev_client

Crate jev_client 

Source
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 null stays 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 misspelt criteria to 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::Unknown instead 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. ApiKey wipes itself on drop and never prints. BaseUrl insists on https:// (plain HTTP only for loopback, or by explicit opt-in), and redirects are not followed, so the key cannot be sent somewhere unexpected.
  • Retries. RetryPolicy defaults to the official SDKs’ behaviour: 2 retries with jittered exponential backoff for 408, 429, 5xx, timeouts and connection failures, honouring Retry-After. 400, 401, 403, 404 and 422 are never retried. Clock keeps tests instant. A Throttle shared by concurrent calls makes a 429 or 529 on one of them slow all of them.
  • Errors. One Error with an ErrorKind mirroring the SDKs’ error classes, carrying the HTTP status, the API’s error_type, and the x-typesafe-request-id. No error ever contains the API key or a request’s state.
  • Logging. tracing events at DEBUG cover method, URL, status, timing, request id and retry decisions. Bodies are traced only on explicit opt-in, and Authorization never 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.
ChoiceAnswer
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.
HttpTransport
A Transport that talks to the TypeSafe API over HTTPS.
HttpTransportBuilder
Configures and builds an HttpTransport.
ModelCard
One model or alias, as listed by the API.
ModelList
The model names an account can send in a request’s model field.
Noul
A yes/no question. The answer is the probability that the answer is yes.
NoulAnswer
The answer to a Noul. It has no confidence: the probability is the signal.
NoulCriteria
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.
ReplyMeta
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.
RetryPolicy
How failed requests are retried.
Score
Rates the state along an ordered rubric. A level’s number is its index in criteria.
ScoreAnswer
The answer to a Score.
SystemClock
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 type field mirrors the question’s type.
ErrorKind
What went wrong, as a category a caller can act on.
InvalidApiKey
Why a string was rejected as an API key. The message never contains the key.
InvalidBaseUrl
Why a string was rejected as a base URL.
Question
One typed question. The type field selects the variant.

Constants§

VERSION
Version of this crate, as published.

Traits§

Clock
A source of time and a way to wait.
Transport
Something that can carry requests to the TypeSafe API.