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
impl Client
Sourcepub fn new(api_key: impl Into<SecretString>) -> Result<Self, Error>
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);Sourcepub fn openrouter(api_key: impl Into<SecretString>) -> Result<Self, Error>
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/");Sourcepub fn typesafe(api_key: impl Into<SecretString>) -> Result<Self, Error>
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);Sourcepub fn for_provider(
provider: Provider,
api_key: impl Into<SecretString>,
) -> Result<Self, Error>
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)?;Sourcepub fn without_api_key(base_url: &str) -> Result<Self, Error>
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")?;Sourcepub fn with_http(http: Client, api_key: impl Into<SecretString>) -> Self
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.
Sourcepub fn from_config(
http: Client,
api_key: impl Into<SecretString>,
config: Config,
) -> Result<Self, Error>
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);Sourcepub fn from_env() -> Result<Self, Error>
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()?;Sourcepub fn with_provider(self, provider: Provider) -> Self
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);Sourcepub fn provider(&self) -> Provider
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);Sourcepub fn with_model(self, model: Model) -> Self
pub fn with_model(self, model: Model) -> Self
Overrides the model sent on every request made by this client.
Sourcepub fn with_surface(self, surface: Surface) -> Self
pub fn with_surface(self, surface: Surface) -> Self
Overrides the OpenRouter HTTP surface. TypeSafe always uses System One.
Sourcepub fn with_api_base(self, base_url: &str) -> Result<Self, Error>
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).
Sourcepub fn with_timeout(self, timeout: Duration) -> Self
pub fn with_timeout(self, timeout: Duration) -> Self
Overrides the per-request timeout (an overall deadline across all retry attempts).
Sourcepub fn with_retry(self, retry: RetryConfig) -> Self
pub fn with_retry(self, retry: RetryConfig) -> Self
Overrides the retry policy.
Sourcepub fn with_context_check(self, enabled: bool) -> Self
pub fn with_context_check(self, enabled: bool) -> Self
Enables or disables the pre-flight context-size estimate.
Sourcepub fn with_session_id(self, session_id: impl Into<String>) -> Self
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.
Sourcepub fn with_user(self, user: impl Into<String>) -> Self
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.
Sourcepub fn with_thresholds(self, thresholds: Thresholds) -> Self
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.
Sourcepub fn thresholds(&self) -> &Thresholds
pub fn thresholds(&self) -> &Thresholds
The configured probability thresholds.
Sourcepub async fn decide<D: Decision>(
&self,
state: impl Into<State>,
) -> Result<D, Error>
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.
Sourcepub async fn decide_with<D: Decision>(
&self,
options: RequestOptions<'_>,
) -> Result<Decided<D>, Error>
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.
Sourcepub async fn ask(
&self,
state: impl Into<State>,
questions: &Questions,
) -> Result<Response, Error>
pub async fn ask( &self, state: impl Into<State>, questions: &Questions, ) -> Result<Response, Error>
Sourcepub async fn noul(
&self,
state: impl Into<State>,
instructions: impl Into<Guidance>,
) -> Result<Noul, Error>
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"Sourcepub async fn choice<T: ChoiceOptions>(
&self,
state: impl Into<State>,
instructions: impl Into<Guidance>,
) -> Result<Choice<T>, Error>
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());Sourcepub async fn score<T: ScoreLevels>(
&self,
state: impl Into<State>,
instructions: impl Into<Guidance>,
) -> Result<Score<T>, Error>
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());Sourcepub async fn run_case(&self, case: &Case) -> Result<CaseResult, Error>
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);Sourcepub async fn raw(&self, options: RequestOptions<'_>) -> Result<Response, Error>
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.