Skip to main content

Client

Struct Client 

Source
pub struct Client { /* private fields */ }
Expand description

Async client for the Jev decision model.

Client is cheap to clone (an Arc-backed reqwest::Client plus one more Arc), so it drops straight into shared application state — a OnceLock, Arc<Client>, or framework extension.

§Examples

use jev::Client;

let client = Client::from_env()?;
let questions = jev::Questions::builder()
    .noul("refund", "Is the customer asking for money back?")
    .build()
    .unwrap();
let response = client.ask("a support ticket about a refund", &questions).await?;
println!("{}", response.answers.noul("refund")?);

Implementations§

Source§

impl Client

Source

pub fn new(api_key: impl Into<SecretString>) -> Result<Self, Error>

Builds an OpenRouter client with the supplied API key and its own connection pool, using whichever TLS backend feature is enabled (rustls-tls by default).

§Errors

Returns Error::Invalid when neither the rustls-tls nor native-tls feature is enabled: with no TLS backend compiled in, this constructor cannot build an HTTPS-capable reqwest::Client. Use Client::with_http with a caller-supplied client in that configuration. Also returns Error::Invalid for an empty key, a key over 4096 bytes, or a key containing whitespace or non-ASCII characters.

§Examples
let client = jev::Client::new(key)?;
assert_eq!(client.provider(), jev::Provider::OpenRouter);
Source

pub fn openrouter(api_key: impl Into<SecretString>) -> Result<Self, Error>

Builds an OpenRouter client directly from an OpenRouter API key.

§Errors

Returns the construction and key-validation errors documented by Client::new.

§Examples
let client = jev::Client::openrouter(key)?;
assert_eq!(client.api_base().as_str(), "https://openrouter.ai/");
Source

pub fn typesafe(api_key: impl Into<SecretString>) -> Result<Self, Error>

Builds a TypeSafe AI client directly from a TypeSafe API key.

Uses https://api.typesafe.ai/v1/systemone and TypeSafe model IDs (jev-1.13.0 for the pinned default, jev-latest for Model::Latest).

§Errors

Returns the construction and key-validation errors documented by Client::new.

§Examples
let client = jev::Client::typesafe(key)?;
assert_eq!(client.provider(), jev::Provider::TypeSafe);
Source

pub fn for_provider( provider: Provider, api_key: impl Into<SecretString>, ) -> Result<Self, Error>

Builds a client with a provider chosen at runtime and its matching API key.

§Errors

Returns the construction and key-validation errors documented by Client::new.

§Examples
let client = jev::Client::for_provider(jev::Provider::TypeSafe, key)?;
Source

pub fn without_api_key(base_url: &str) -> Result<Self, Error>

Builds a client that sends no Authorization header at all, for a System One-compatible backend a caller hosts themselves.

Some self-hosted backends (a local model server, a proxy that injects its own credentials, a demo endpoint that takes no key) neither expect nor accept a bearer token; every other Client constructor sends one unconditionally. base_url may use http:// for a loopback address without the opt-in Client::with_api_base otherwise requires, since a backend a caller hosts on their own machine is exactly the case that check exists to allow.

§Errors

Returns Error::Invalid when neither the rustls-tls nor native-tls feature is enabled (see Client::new), or when base_url fails to parse or uses a non-https, non-loopback scheme.

§Examples
use jev::Client;

let client = Client::without_api_key("http://127.0.0.1:8099")?;
Source

pub fn with_http(http: Client, api_key: impl Into<SecretString>) -> Self

Builds a client that shares a caller-owned reqwest::Client and connection pool. This is the right choice inside a service that already owns an HTTP client, and the only way to supply a custom TLS configuration (for example a pinned internal CA), or to build with neither TLS feature enabled. The key is validated before sending each request.

Source

pub fn from_config( http: Client, api_key: impl Into<SecretString>, config: Config, ) -> Result<Self, Error>

Builds a client from a caller-supplied HTTP client, API key, and Config, for the config-file path.

§Errors

Returns Error::Invalid if the API key fails the validation documented by Client::new.

§Examples
let config = jev::Config { provider: jev::Provider::TypeSafe, ..Default::default() };
let client = jev::Client::from_config(reqwest::Client::new(), key, config)?;
assert_eq!(client.provider(), jev::Provider::TypeSafe);
Source

pub fn from_env() -> Result<Self, Error>

Builds a client from environment variables, with an optional JEV_BASE_URL.

JEV_PROVIDER=openrouter|typesafe selects the service explicitly; the key comes from JEV_API_KEY or that provider’s OPENROUTER_API_KEY / TYPESAFE_API_KEY. A key belonging to the other provider is never used. Without JEV_PROVIDER, keys are tried in this order: JEV_API_KEY (OpenRouter), OPENROUTER_API_KEY, then TYPESAFE_API_KEY (TypeSafe).

§Errors

Returns Error::MissingApiKey when no matching key is set, or Error::Invalid for an unknown provider, an invalid key, or an invalid JEV_BASE_URL (see Client::with_api_base).

§Examples
// Configure TYPESAFE_API_KEY and JEV_PROVIDER=typesafe in your environment.
let client = jev::Client::from_env()?;
Source

pub fn with_provider(self, provider: Provider) -> Self

Selects the hosted provider while preserving custom HTTP and base URL settings.

Supply the selected provider’s key at construction. TypeSafe always uses System One; OpenRouter uses the configured surface.

§Examples
let client = jev::Client::with_http(reqwest::Client::new(), key)
    .with_provider(jev::Provider::TypeSafe);
Source

pub fn provider(&self) -> Provider

The hosted provider configured for this client.

§Examples
let client = jev::Client::with_http(reqwest::Client::new(), "key");
assert_eq!(client.provider(), jev::Provider::OpenRouter);
Source

pub fn with_model(self, model: Model) -> Self

Overrides the model sent on every request made by this client.

Source

pub fn with_surface(self, surface: Surface) -> Self

Overrides the OpenRouter HTTP surface. TypeSafe always uses System One.

Source

pub fn with_api_base(self, base_url: &str) -> Result<Self, Error>

Overrides the API base URL (scheme + host).

§Errors

Returns Error::Invalid when base_url fails to parse, or uses a scheme other than https (http is accepted only for local mocks; see the crate’s security posture docs).

Source

pub fn with_timeout(self, timeout: Duration) -> Self

Overrides the per-request timeout (an overall deadline across all retry attempts).

Source

pub fn with_retry(self, retry: RetryConfig) -> Self

Overrides the retry policy.

Source

pub fn with_context_check(self, enabled: bool) -> Self

Enables or disables the pre-flight context-size estimate.

Source

pub fn with_session_id(self, session_id: impl Into<String>) -> Self

Sets a default session identifier applied to every request unless overridden per-call by RequestOptions::with_session_id.

Source

pub fn with_user(self, user: impl Into<String>) -> Self

Sets a default user identifier applied to every request unless overridden per-call by RequestOptions::with_user.

Source

pub fn with_thresholds(self, thresholds: Thresholds) -> Self

Sets the named probability thresholds this client carries for callers that want to read them back via Client::thresholds.

Source

pub fn thresholds(&self) -> &Thresholds

The configured probability thresholds.

Source

pub fn api_base(&self) -> Url

The effective API base URL.

Source

pub async fn decide<D: Decision>( &self, state: impl Into<State>, ) -> Result<D, Error>

Typed path: sends D::questions(), parses the answers back into D.

This is the 90% API. It deliberately drops the response envelope (id, usage, cost); use Client::decide_with when that data is needed.

§Errors

Any Error from the underlying request, or from Decision::from_answers if the server’s answers do not match D’s shape.

Source

pub async fn decide_with<D: Decision>( &self, options: RequestOptions<'_>, ) -> Result<Decided<D>, Error>

Typed path with per-call knobs (session, user, trace, model override).

§Errors

Any Error from the underlying request, or from Decision::from_answers.

Source

pub async fn ask( &self, state: impl Into<State>, questions: &Questions, ) -> Result<Response, Error>

Dynamic path: sends caller-supplied questions, returns the raw answer map.

§Errors

Any Error from the underlying request.

Source

pub async fn noul( &self, state: impl Into<State>, instructions: impl Into<Guidance>, ) -> Result<Noul, Error>

Single-question convenience: asks one noul question and returns the typed Noul answer directly, without a Decision struct.

For a one-off yes/no gate that does not warrant its own struct. For more than one question in a single request, or to keep the question and its criteria next to a named type, use #[derive(Decision)] or Client::ask instead.

§Errors

Error::Invalid if instructions fails Questions’s validation (empty, oversized); otherwise any Error from the underlying request.

§Examples
let is_refund = client.noul("Please refund my order.", "Is this a refund request?").await?;
println!("{is_refund}"); // Display: "yes, 88% sure"
Source

pub async fn choice<T: ChoiceOptions>( &self, state: impl Into<State>, instructions: impl Into<Guidance>, ) -> Result<Choice<T>, Error>

Single-question convenience: asks one choice question over T::options() and returns the typed Choice<T> answer directly, without a Decision struct.

T supplies both the wire criteria (T::options()) and the typed result, the same as a Choice<T> field on a #[derive(Decision)] struct would.

§Errors

Error::Invalid if instructions fails validation; Error::UnknownChoice if the server picks an option outside T; otherwise any Error from the underlying request.

§Examples
use jev::ChoiceOptions;

#[derive(Debug, Clone, Copy, PartialEq, Eq, ChoiceOptions)]
enum Team {
    /// Billing issues.
    Payments,
    /// UI issues.
    Frontend,
}

let team = client.choice::<Team>("a checkout ticket", "Which team owns this?").await?;
println!("{:?}", team.value());
Source

pub async fn score<T: ScoreLevels>( &self, state: impl Into<State>, instructions: impl Into<Guidance>, ) -> Result<Score<T>, Error>

Single-question convenience: asks one score question over T::levels() and returns the typed Score<T> answer directly, without a Decision struct.

§Errors

Error::Invalid if instructions fails validation; Error::ScoreRange if the server’s score falls outside T’s levels; otherwise any Error from the underlying request.

§Examples
use jev::ScoreLevels;

#[derive(Debug, Clone, Copy, PartialEq, Eq, ScoreLevels)]
enum Urgency {
    /// Can wait.
    Low,
    /// Blocking revenue.
    High,
}

let urgency = client.score::<Urgency>("a checkout ticket", "How urgent is this?").await?;
println!("{:?}", urgency.nearest());
Source

pub async fn run_case(&self, case: &Case) -> Result<CaseResult, Error>

Runs one predefined Case: builds its questions, sends its state, and returns the response tagged with the case’s id.

This is the config-file counterpart of Client::ask: ask takes questions assembled in code, run_case takes both the state and the questions from a Case loaded via crate::CaseSet::from_yaml_str / crate::CaseSet::from_json_str / crate::CaseSet::from_file. For many cases at once with bounded concurrency, see crate::run_cases (the batch feature).

§Errors

Error::Invalid if case.questions fails validation (this should not happen for a Case obtained from a successfully loaded crate::CaseSet, which validates eagerly at load time); otherwise any Error from the underlying request.

§Examples
let result = client.run_case(case).await?;
println!("{}: {:?}", result.id, result.response.answers);
Source

pub async fn raw(&self, options: RequestOptions<'_>) -> Result<Response, Error>

Escape hatch: full request in (RequestOptions::with_questions required), full Response out.

§Errors

Error::Invalid if options has no questions set; otherwise any Error from the underlying request.

Trait Implementations§

Source§

impl Clone for Client

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Client

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more