Skip to main content

Crate jev

Crate jev 

Source
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:

PrimitiveQuestionAnswer shape
NoulDoes 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

FeatureDefaultEffect
deriveyesRe-exports the Decision/ChoiceOptions/ScoreLevels derives.
retryyesBounded retry loop honouring Retry-After.
rustls-tlsyesreqwest over rustls with the aws-lc-rs backend.
native-tlsnoreqwest over the platform TLS stack.
batchnodecide_all and run_cases, bounded-concurrency helpers.
yamlnoCaseSet::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.
CaseNoulCriteria
The "true"/"false" criteria pair for a CaseQuestion::Noul.
CaseResult
The result of running one Case through crate::Client::run_case: the case’s id alongside the raw Response.
CaseSet
A batch of Cases loaded from one YAML/JSON document: the config-file counterpart of hand-assembling many Questions values in code.
Choice
A choice answer, carrying the typed value alongside its raw probabilities.
ChoiceAnswer
A choice answer.
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 noul answer: P(yes), plus threshold arithmetic.
NoulAnswer
A noul answer: P(yes).
NoulCriteria
The "true"/"false" criteria pair for a Question::Noul.
Questions
An ordered map of question key to Question.
QuestionsBuilder
Validating builder for Questions, the config-driven / dynamic-question path.
RequestOptions
Per-call request options for Client::decide_with and Client::raw.
Response
The full response body from either surface.
ResponseMeta
The response envelope without the answers: identifiers, model snapshot, usage, cost, and latency.
RetryConfig
Bounded retry configuration honouring Retry-After.
Score
A score answer, carrying the raw continuous score alongside the typed nearest level.
ScoreAnswer
A score answer.
Thresholds
Named, runtime-tunable probability thresholds.
TraceConfig
Opaque, pass-through trace configuration.
Usage
Token and cost accounting for one request, as reported by the gateway.

Enums§

Answer
One answered question.
CaseQuestion
One configured question inside a Case: the same noul/choice/score shape crate::Question sends on the wire, deserialized from a case file instead of built through QuestionsBuilder.
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, or score.
State
The state a crate::Question set is evaluated against.
Surface
Which HTTP surface a crate::Client talks 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. See Model::Jev113 for the rationale.

Traits§

ChoiceOptions
A fieldless enum usable as choice criteria.
Decision
A set of questions about one state, answered as one struct.
ScoreLevels
A fieldless enum usable as an ordered score scale, lowest level first.

Functions§

decide_all
Runs one decision per state with bounded concurrency, preserving input order.
run_cases
Runs many predefined Cases (see crate::CaseSet) with bounded concurrency, preserving input order.

Derive Macros§

ChoiceOptions
Derives impl jev::ChoiceOptions for a fieldless enum.
Decision
Derives impl jev::Decision for a struct whose fields are Noul, Choice<T>, Score<T>, or Option<_> of those.
ScoreLevels
Derives impl jev::ScoreLevels for a fieldless enum.