Struct Client 

pub struct Client { /* private fields */ }

Asynchronous TypeSafe System One client.

Cheap to clone (Arc internally) and safe to share across tasks (Send + Sync).

Examples

use typesafe_rs::{questions, Client, ClientConfig, Question};

let client = ClientConfig::new().api_key("sk-...").build()?;
let response = client
    .system_one(
        "Help! My payouts have been failing for 3 days.",
        questions! { "urgent" => Question::noul("Does this convey urgency?") },
    )
    .await?;
assert!(response.noul("urgent").is_some());

Implementations

impl Client

pub fn new(config: ClientConfig) -> Result<Self, Error>

Build a client. Unset fields fall back to the process environment, then defaults.

Errors

Returns Error::MissingApiKey when no key is configured, or Error::InvalidRequest for invalid timeout / retry / URL values.

Examples found in repository

examples/quickstart.rs (lines 20-25)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mock = MockServer::start().await;
    mock.on_system_one().respond(json!({
        "urgent": noul(0.97),
    }));

    let client = Client::new(ClientConfig {
        api_key: Some("test".into()),
        base_url: Some(mock.url()),
        default_model: Some("jev-latest".into()),
        ..ClientConfig::default()
    })?;

    let response = client
        .system_one(
            "Help! My payouts have been failing for 3 days.",
            questions! {
                "urgent" => Question::noul("Does this convey urgency?")
                    .when_true("Explicitly time-sensitive")
                    .when_false("No time pressure"),
            },
        )
        .await?;

    println!("urgent noul = {:?}", response.noul("urgent"));
    println!("request id  = {:?}", response.meta.request_id);
    Ok(())
}

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

Self::new using TYPESAFE_* from the process environment.

pub fn new_with_env( config: ClientConfig, lookup: impl FnMut(&str) -> Option<String>, ) -> Result<Self, Error>

Like Self::new, but environment fallbacks come from lookup.

Intended for tests and embeddings that should not read process env.

pub fn default_model(&self) -> &str

Default model used when a request omits model.

pub fn base_url(&self) -> &Url

Resolved API root, without a trailing slash.

pub async fn system_one( &self, state: impl Serialize, questions: Questions, ) -> Result<SystemOneResponse, Error>

Evaluate state against questions using client defaults.

state may be a string, object, or array. Question keys are returned on SystemOneResponse::answers.

Errors

Returns Error::InvalidRequest before any network call when the question map is empty or a Choice/Score is under-specified. Network and API failures use the rest of Error.

Examples found in repository

examples/quickstart.rs (lines 28-35)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mock = MockServer::start().await;
    mock.on_system_one().respond(json!({
        "urgent": noul(0.97),
    }));

    let client = Client::new(ClientConfig {
        api_key: Some("test".into()),
        base_url: Some(mock.url()),
        default_model: Some("jev-latest".into()),
        ..ClientConfig::default()
    })?;

    let response = client
        .system_one(
            "Help! My payouts have been failing for 3 days.",
            questions! {
                "urgent" => Question::noul("Does this convey urgency?")
                    .when_true("Explicitly time-sensitive")
                    .when_false("No time pressure"),
            },
        )
        .await?;

    println!("urgent noul = {:?}", response.noul("urgent"));
    println!("request id  = {:?}", response.meta.request_id);
    Ok(())
}

examples/triage.rs (lines 26-41)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mock = MockServer::start().await;
    mock.on_system_one().respond(json!({
        "urgent": noul(0.97),
        "team": choice("technical", 0.82),
        "frustration": score(1.6, 0.78),
    }));

    let client = ClientConfig::new()
        .api_key("test")
        .base_url(mock.url())
        .build()?;

    let response = client
        .system_one(
            "Help! My payouts have been failing for 3 days.",
            questions! {
                "urgent" => Question::noul("Does this convey urgency?")
                    .when_true("Explicitly time-sensitive")
                    .when_false("No time pressure"),
                "team" => Question::choice("Which team should handle this?")
                    .option("billing", "Payments, invoicing, refunds")
                    .option("technical", "Bugs, outages, integrations")
                    .option("sales", "Pricing, upgrades, new accounts"),
                "frustration" => Question::score("How frustrated is the customer?")
                    .level("Calm")
                    .level("Frustrated")
                    .level("Very angry"),
            },
        )
        .await?;

    println!("urgent      = {:?}", response.noul("urgent"));
    println!(
        "team        = {:?}",
        response.choice("team").map(|c| c.choice)
    );
    println!(
        "frustration = {:?}",
        response.score("frustration").map(|s| s.score)
    );
    Ok(())
}

pub async fn system_one_with( &self, req: &SystemOneRequest, opts: CallOptions, ) -> Result<SystemOneResponse, Error>

Evaluate a fully specified request with per-call options.

pub fn models(&self) -> Models<'_>

Access the Models resource.

Examples found in repository

examples/models.rs (line 28)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mock = MockServer::start().await;
    mock.on_models().respond(json!({
        "models": [{
            "name": "jev-latest",
            "description": "TypeSafe flagship",
            "release_date": "2026-01-01"
        }]
    }));

    let client = ClientConfig::new()
        .api_key("test")
        .base_url(mock.url())
        .build()?;

    client.warm_up().await?;
    for model in client.models().list().await? {
        println!("{} — {}", model.name, model.description);
    }
    Ok(())
}

pub async fn warm_up(&self) -> Result<(), Error>

Establish a pooled connection by calling GET /v1/models.

Examples found in repository

examples/models.rs (line 27)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mock = MockServer::start().await;
    mock.on_models().respond(json!({
        "models": [{
            "name": "jev-latest",
            "description": "TypeSafe flagship",
            "release_date": "2026-01-01"
        }]
    }));

    let client = ClientConfig::new()
        .api_key("test")
        .base_url(mock.url())
        .build()?;

    client.warm_up().await?;
    for model in client.models().list().await? {
        println!("{} — {}", model.name, model.description);
    }
    Ok(())
}

Trait Implementations

impl Backend for Client

fn name(&self) -> &str

Stable backend name, e.g. "typesafe".

fn system_one( &self, req: &SystemOneRequest, opts: &CallOptions, ) -> impl Future<Output = Result<SystemOneResponse, Error>> + Send

Evaluate req with per-call options.

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.