Expand description
§jev
A typed Rust SDK for the Jev decision model — a System One model that answers typed questions about a state you send it, with calibrated probabilities, instead of prose.
Three primitives, three questions:
| Primitive | Question | Answer shape |
|---|---|---|
Noul | Does this condition hold? | P(yes) |
Choice<T> | Which one of these options? | an enum variant, plus confidence |
Score<T> | Where on an ordered scale? | a continuous position, plus the nearest level |
§The typed path
One Rust type is one request and one answer struct. /// doc comments on struct
fields become instructions; /// on enum variants become that option’s
criteria — there is exactly one copy of the prompt, and cargo doc shows a
reviewer precisely what the model is asked.
use jev::{Choice, ChoiceOptions, Client, Decision, Noul, Score, ScoreLevels};
/// A support ticket triage decision.
#[derive(Debug, Decision)]
struct Triage {
/// Is the customer reporting a software defect?
#[jev(yes = "The customer describes broken or unexpected product behavior.",
no = "The customer is asking a question or requesting a feature.")]
is_bug: Noul,
/// Which team should own this ticket?
team: Choice<Team>,
/// How urgent is this ticket?
urgency: Score<Urgency>,
}
/// Owning team for a ticket.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ChoiceOptions)]
enum Team {
/// Checkout, billing, or payment processing issues.
Payments,
/// Rendering, layout, or browser compatibility issues.
Frontend,
/// Login, permissions, or profile issues.
Account,
}
/// Ordered urgency scale, lowest first.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ScoreLevels)]
enum Urgency {
/// Can wait for the next release.
NextRelease,
/// Should be fixed this week.
ThisWeek,
/// Blocking revenue right now.
BlockingRevenue,
}
let client = Client::from_env()?;
let triage: Triage = client.decide("a customer ticket about a checkout error").await?;
if triage.is_bug.is_yes(0.9) {
if let Some(team) = triage.team.accept(0.7) {
println!("route to {team:?}");
}
}
let urgency: Urgency = triage.urgency.nearest();
println!("{urgency:?}");§Providers and API keys
Construct a client with a key loaded by your application:
let openrouter = jev::Client::openrouter(openrouter_key)?;
let typesafe = jev::Client::typesafe(typesafe_key)?;Client::new defaults to OpenRouter. Client::for_provider accepts a
runtime Provider; Config::provider supports YAML configuration.
TypeSafe uses /v1/systemone with jev-1.13.0 for the pinned default model,
and jev-latest for Model::Latest. OpenRouter retains its existing paths
and model IDs. Custom model IDs are never rewritten.
Client::from_env reads JEV_PROVIDER=openrouter|typesafe when set and
uses JEV_API_KEY or the selected provider’s key variable. Without an explicit
provider, key precedence is JEV_API_KEY (OpenRouter), OPENROUTER_API_KEY,
then TYPESAFE_API_KEY (TypeSafe).
§Predefined cases from YAML/JSON
For a fixed batch of (state, questions) pairs — a fixture file of support
tickets, a regression suite of prior decisions — CaseSet loads them from one
YAML/JSON document instead of assembling each Questions value in code:
use jev::CaseSet;
let json = r#"{"cases": [{
"id": "ticket-001",
"state": "Customer wants a refund for a duplicate charge.",
"questions": {
"refund": {"type": "noul", "instructions": "Is the customer asking for money back?"}
}
}]}"#;
let cases = CaseSet::from_json_str(json).unwrap();use jev::{CaseSet, Client};
let cases = CaseSet::from_file("cases.yaml").await?;
let client = Client::from_env()?;
for case in &cases {
let result = client.run_case(case).await?;
println!("{}: {:?}", result.id, result.response.answers);
}See CaseSet’s docs for the file format, and run_cases (behind the batch
feature) for running the whole set with bounded concurrency.
§The dynamic path
For question sets assembled at runtime from configuration, Questions::builder
is the same wire logic the derive uses, minus the compile-time checks:
use jev::Questions;
let questions = Questions::builder()
.noul("refund", "Is the customer asking for money back?")
.choice("team", "Which team should own this?", [("payments", "Billing."), ("frontend", "UI.")])
.build()
.unwrap();§Choosing thresholds
confidence is a calibration signal, not accuracy: a Choice<T> with
confidence = 0.95 means the model is well-calibrated to be right about 95% of
the time on inputs like this one, assuming the model’s calibration holds for your
distribution of states. The SDK never picks a threshold for you — see Noul::decide,
Choice::accept, and crate::Thresholds — because the right threshold trades
off automation rate against error tolerance, which is a product decision, not an
SDK one. Escalate the ambiguous band (between is_yes/is_no, or below
accept’s threshold) to a human reviewer rather than picking a default that
silently mispredicts on the cases the model itself is uncertain about.
§Feature flags
| Feature | Default | Effect |
|---|---|---|
derive | yes | Re-exports the Decision/ChoiceOptions/ScoreLevels derives. |
retry | yes | Bounded retry loop honouring Retry-After. |
rustls-tls | yes | reqwest over rustls with the aws-lc-rs backend. |
native-tls | no | reqwest over the platform TLS stack. |
batch | no | decide_all and run_cases, bounded-concurrency helpers. |
yaml | no | CaseSet::from_yaml_str / CaseSet::from_file for .yaml/.yml. |
Structs§
- Answers
- The full set of answers for one request: an ordered map of question key to
Answer. - Case
- One predefined case: one state, one or more questions, one API call.
- Case
Noul Criteria - The
"true"/"false"criteria pair for aCaseQuestion::Noul. - Case
Result - The result of running one
Casethroughcrate::Client::run_case: the case’sidalongside the rawResponse. - CaseSet
- A batch of
Cases loaded from one YAML/JSON document: the config-file counterpart of hand-assembling manyQuestionsvalues in code. - Choice
- A
choiceanswer, carrying the typed value alongside its raw probabilities. - Choice
Answer - A
choiceanswer. - Client
- Async client for the Jev decision model.
- Config
- Deserializable client configuration, for the config-file path.
- Decided
- A typed decision plus the response envelope: id, model snapshot, usage, and cost.
- Noul
- A
noulanswer:P(yes), plus threshold arithmetic. - Noul
Answer - A
noulanswer:P(yes). - Noul
Criteria - The
"true"/"false"criteria pair for aQuestion::Noul. - Questions
- An ordered map of question key to
Question. - Questions
Builder - Validating builder for
Questions, the config-driven / dynamic-question path. - Request
Options - Per-call request options for
Client::decide_withandClient::raw. - Response
- The full response body from either surface.
- Response
Meta - The response envelope without the answers: identifiers, model snapshot, usage, cost, and latency.
- Retry
Config - Bounded retry configuration honouring
Retry-After. - Score
- A
scoreanswer, carrying the raw continuous score alongside the typed nearest level. - Score
Answer - A
scoreanswer. - Thresholds
- Named, runtime-tunable probability thresholds.
- Trace
Config - Opaque, pass-through trace configuration.
- Usage
- Token and cost accounting for one request, as reported by the gateway.
Enums§
- Answer
- One answered question.
- Case
Question - One configured question inside a
Case: the samenoul/choice/scoreshapecrate::Questionsends on the wire, deserialized from a case file instead of built throughQuestionsBuilder. - Error
- Everything that can go wrong calling Jev, in one non-exhaustive enum.
- Guidance
- Free-form guidance text sent to the model: a question’s
instructions, or one option’s criteria. - Model
- A Jev / System One model identifier.
- Provider
- The hosted service that receives requests and authenticates the API key.
- Question
- One question sent to the model:
noul,choice, orscore. - State
- The state a
crate::Questionset is evaluated against. - Surface
- Which HTTP surface a
crate::Clienttalks to. - Verdict
- A yes/no judgment that may also come out undecided.
Constants§
- DEFAULT_
MODEL - The pinned default model. A bump is one reviewable line, deliberately never
Model::Latest. SeeModel::Jev113for the rationale.
Traits§
- Choice
Options - A fieldless enum usable as
choicecriteria. - Decision
- A set of questions about one state, answered as one struct.
- Score
Levels - A fieldless enum usable as an ordered
scorescale, lowest level first.
Functions§
- decide_
all - Runs one decision per state with bounded concurrency, preserving input order.
- run_
cases - Runs many predefined
Cases (seecrate::CaseSet) with bounded concurrency, preserving input order.
Derive Macros§
- Choice
Options - Derives
impl jev::ChoiceOptionsfor a fieldless enum. - Decision
- Derives
impl jev::Decisionfor a struct whose fields areNoul,Choice<T>,Score<T>, orOption<_>of those. - Score
Levels - Derives
impl jev::ScoreLevelsfor a fieldless enum.