Skip to main content

Crate jevrs

Crate jevrs 

Source
Expand description

§Overview

Jev evaluates several typed questions against the same JSON state in one request. jevrs adds compile-time question sets, a runtime builder, retry control, and portable transports around that API.

§Quick start

Declare criteria once, derive a QuestionSet, and call Client::ask. Answered<T> exposes the generated fields directly and retains the model version and Usage. The example uses Client::from_env; see Getting a client for explicit configuration and custom transports.

use jevrs::{Choice, Client, Levels, Noul, Options, Questions, Score};

#[derive(Clone, Copy, Debug, Eq, Options, PartialEq)]
enum Department {
    /// Payments, invoicing, refunds
    Billing,
    /// Bugs, outages, integrations
    Technical,
    Sales,
}

#[derive(Clone, Copy, Debug, Eq, Levels, Ord, PartialEq, PartialOrd)]
enum Frustration {
    /// Calm
    Calm,
    /// Frustrated
    Frustrated,
    /// Very angry
    VeryAngry,
}

#[derive(Questions)]
struct Triage {
    #[jev(
        noul = "Does this convey urgency?",
        yes = "Explicitly time-sensitive",
        no = "No urgency expressed"
    )]
    is_urgent: Noul,
    #[jev(choice = "Which team should handle this?")]
    department: Choice<Department>,
    #[jev(score = "How frustrated is the customer?")]
    frustration: Score<Frustration>,
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    let triage = client
        .ask::<Triage>(&"Help! My payouts have been failing for 3 days.")
        .await?;

    println!("urgent: {:.0}%", triage.is_urgent.p.get() * 100.0);
    println!("department: {:?}", triage.department.pick);
    println!("frustration: {:.2}", triage.frustration.expected());
    Ok(())
}

Run the complete native program in the native-derive example.

§Getting a client

Client::from_env reads TYPESAFE_API_KEY and, optionally, TYPESAFE_BASE_URL or TYPESAFE_API_BASE.

Client::builder takes the key and settings explicitly through ClientBuilder::api_key, ClientBuilder::base_url, ClientBuilder::model, ClientBuilder::retry, and ClientBuilder::header.

use jevrs::{Client, Model};

let client = Client::from_env()?;

let client = Client::builder()
    .api_key("your-api-key")
    .base_url("https://api.typesafe.ai")
    .model(Model::LATEST)
    .build()?;

With your own HTTP stack, implement Transport and start from ClientBuilder::new. Retries stay off until you supply a Sleep.

§The typed path

Use the typed path when question IDs and criteria are part of your program.

use jevrs::{Indexed, Levels, Options};

#[derive(Clone, Copy, Debug, Eq, Options, PartialEq)]
enum Route {
    /// Account and payment questions
    Billing,
    #[jev(key = "tech", desc = "Bugs and outages")]
    Technical,
}

#[derive(Clone, Copy, Debug, Eq, Levels, Ord, PartialEq, PartialOrd)]
enum Priority {
    /// Normal queue
    Normal,
    /// Immediate attention
    Urgent,
}

assert_eq!(Route::Technical.key(), "tech");
assert_eq!(Priority::all(), &[Priority::Normal, Priority::Urgent]);

Options gives a choice enum stable keys and optional descriptions. Levels turns an ordered enum into described score levels. Questions generates a QuestionSet, handles, and answer fields. Client::ask returns Answered<T>, so department.pick stays an enum.

§The dynamic path

Use Questions when criteria come from configuration or a database. The builder validates the criteria and names the question in Error::InvalidCriteria. Use DynOptions and DynLevels to validate once up front, such as at startup from configuration, and reuse the criteria across batches. Keep each typed Handle, then read the matching answer with Answers::get. Dynamic choices produce DynChoiceAnswer; dynamic scores produce DynScoreAnswer.

use jevrs::{Client, Questions};

let mut questions = Questions::new();
let urgent = questions.noul_with(
    "is_urgent",
    "Does this convey urgency?",
    "Explicitly time-sensitive",
    "No urgency expressed",
)?;
let department = questions.choice_dyn(
    "department",
    "Which team should handle this?",
    [
        ("billing", Some("Payments, invoicing, refunds")),
        ("technical", Some("Bugs, outages, integrations")),
        ("sales", None),
    ],
)?;
let frustration = questions.score_dyn(
    "frustration",
    "How frustrated is the customer?",
    ["Calm", "Frustrated", "Very angry"],
)?;

let client = Client::from_env()?;
let answers = client
    .evaluate(&"Help! My payouts have been failing for 3 days.", &questions)
    .await?;
println!("urgent: {:.0}%", answers.get(urgent).p.get() * 100.0);
println!("department: {}", answers.get(department).pick);
println!("frustration: {:.2}", answers.get(frustration).expected());

See the native-dynamic example for the complete program.

§Mixing both

A Questions builder can use a static Options enum or Levels enum beside runtime-defined criteria. Prefer this when only part of a request is configured at runtime.

use jevrs::{Model, Options, Questions, encode};

#[derive(Clone, Copy, Debug, Eq, Options, PartialEq)]
enum Department {
    /// Payments, invoicing, refunds
    Billing,
    /// Bugs, outages, integrations
    Technical,
}

let mut questions = Questions::new();
questions.choice::<Department>(
    "department",
    "Which team should handle this?",
)?;
let request = encode(&Model::LATEST, &"A customer's card was declined.", &questions)?;
let request: serde_json::Value = serde_json::from_slice(&request)?;
assert_eq!(
    request["questions"]["department"]["criteria"]["billing"],
    "Payments, invoicing, refunds",
);

§Transports

The default transport follows the target: DefaultTransport resolves to ReqwestTransport on native targets, Wasip2Transport on wasm32-wasip2, and Wasip3Transport on wasm32-wasip3. See Transport for a worked example, and use ClientBuilder::new when you already have an HTTP stack. Mark only safe transport failures as retryable: a failure before any bytes reached the server, never one after a partial send.

On docs.rs, use the target selector to view the WASI transports under wasm32-wasip2 and wasm32-wasip3, since they do not exist in the host build.

§Retries and errors

RetryPolicy retries HTTP 429 and 529 responses plus failures that Transport::is_retryable accepts. A server Retry-After value wins over exponential backoff. A custom transport needs a Sleep implementation to wait between attempts; NoSleep disables retries. Client::builder installs the target’s matching sleeper.

Match the non-exhaustive Error enum by category. API errors retain parsed details, the raw body, and ErrorDetail::request_id for support requests.

use jevrs::{Client, Error, RetryPolicy};

fn report(error: &Error) {
    match error {
        Error::Auth { detail, .. }
        | Error::BadRequest { detail, .. }
        | Error::RateLimited { detail, .. }
        | Error::Overloaded { detail }
        | Error::Http { detail, .. } => {
            eprintln!("API error; request id: {:?}", detail.request_id);
        }
        Error::Transport(source) => eprintln!("transport error: {source}"),
        other => eprintln!("request failed: {other}"),
    }
}

let client = Client::builder()
    .retry(RetryPolicy { max_retries: 4, ..RetryPolicy::default() })
    .from_env()?
    .build()?;

§Feature flags

FeatureDefaultUse it for
deriveyesThe Options, Levels, and Questions derives.
reqwestyesNative HTTP with reqwest’s rustls backend and Tokio sleep.
native-tlsnoNative HTTP with the platform TLS backend.
test-utilnoMockTransport and MockSleep in downstream tests.
webnoReserved; it does not provide a browser transport yet.

§Limits

Jev 1.13 accepts at most 64,000 tokens total. The state plus the longest question may use at most 32,000 tokens. jevrs leaves token counting to the server. A request needs at least one question.

use jevrs::{DynLevels, Error};

let levels = (0..11).map(|index| format!("Level {index}"));
assert!(matches!(
    DynLevels::new(levels),
    Err(Error::InvalidCriteria { .. }),
));

Structs§

Answered
A typed question-set result together with response metadata.
Answers
Eagerly decoded answers for one Questions batch.
ArrayMap
Dense per-key storage for a static Options or Levels implementation.
ChoiceAnswer
The selected option and probability distribution for a static choice.
ChoiceQ
Marker to use when Options define a choice at compile time.
Client
An async Jev API client backed by target-selected or custom I/O.
ClientBuilder
Configures a Client without coupling it to a particular runtime.
Confidence
A model confidence constrained to the inclusive range from zero to one.
DynChoiceAnswer
The selected option and probability distribution for a dynamic choice.
DynChoiceQ
Marker returned for a choice built with runtime-defined crate::DynOptions.
DynLevels
A runtime-defined ordered scoring scale.
DynOptions
A runtime-defined set of named choices.
DynScoreAnswer
The expected score and probability distribution for dynamic levels.
DynScoreQ
Marker returned for a score built with runtime-defined crate::DynLevels.
ErrorDetail
Information recovered from an unsuccessful API response body.
Handle
A typed reference to one question in a Questions batch.
Instructions
Guidance supplied with a Jev question as a JSON value.
MockErrortest-util
A transport failure returned by MockTransport.
MockSleeptest-util
A sleeper that records delays and completes immediately.
MockTransporttest-util
An in-memory transport that records requests and replays canned outcomes.
Model
A Jev model name used for requests and reported by responses.
ModelInfo
A Jev model advertised by Client::models.
NoSleep
Disables waiting and, when used by a client builder, all retries.
NoulAnswer
The probability assigned to a yes/no question’s positive outcome.
NoulQ
Marker to use for a yes/no question in a typed handle or QuestionSet.
Probability
A probability constrained to the inclusive range from zero to one.
Questions
An insertion-ordered collection of questions sent in one Jev request.
ReqwestTransport(native-tls or reqwest) and non-WebAssembly
Sends Jev requests with reqwest’s native HTTP client.
RetryPolicy
Controls retry count and exponential-backoff timing.
ScoreAnswer
The expected score and probability distribution for static levels.
ScoreQ
Marker to use when Levels define a score scale at compile time.
TokioSleep(native-tls or reqwest) and non-WebAssembly
Waits between retry attempts with Tokio’s timer.
Usage
Token counts consumed while producing a Jev response.

Enums§

Error
An error produced while constructing, sending, or decoding a Jev request.

Traits§

Indexed
A finite set whose values have a dense canonical order.
Levels
A statically defined ordered scoring scale.
MaybeSend
A portability bound for futures returned by Transport and Sleep.
Options
A statically defined set of named choices.
Question
Binds a question marker to the answer type returned for it.
QuestionSet
Defines a reusable, statically typed set of Jev questions.
Sleep
Pauses a retry loop without prescribing an async runtime.
Transport
Sends fully framed HTTP requests for the Jev client.

Functions§

classify
Classifies an unsuccessful HTTP response and preserves its API details.
decode
Decodes and validates a Jev response for questions without network I/O.
encode
Encodes a Jev request body without performing network I/O.

Type Aliases§

Choice
Readable alias to use for a static choice field in a crate::QuestionSet.
DefaultSleep(native-tls or reqwest) and non-WebAssembly
The target-selected retry sleeper.
DefaultTransport(native-tls or reqwest) and non-WebAssembly
The target-selected HTTP transport.
Noul
Readable alias to use for a yes/no field in a crate::QuestionSet.
Score
Readable alias to use for a static score field in a crate::QuestionSet.

Derive Macros§

Levelsderive
Derives jevrs::Levels for an ordered unit-variant enum.
Optionsderive
Derives jevrs::Options for a unit-variant enum.
Questionsderive
Derives a reusable, statically typed Jev question set from named fields.