typesafeai-sdk 0.4.0

Rust SDK for TypeSafe AI — typed judgments from System One models like Jev
Documentation

typesafeai-sdk

crates.io docs.rs license

Rust SDK for TypeSafe AI — typed judgments from System One models like Jev.

TypeSafe turns natural language and application state into typed judgments and probabilities that code can use directly. Instead of generating text, System One models return structured answers: probabilities, choices, and scores you can branch on, rank with, or feed into downstream logic.

Installation

[dependencies]
typesafeai-sdk = "0.3"

Requires Rust 1.88+ and uses rustls-tls (no OpenSSL dependency).

Quickstart

Set your API key:

export TYPESAFE_API_KEY=apikey_...

Ask a question:

use typesafeai_sdk::{TypeSafeClient, noul, choice, score, Question};
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = TypeSafeClient::from_env()?;

    let mut questions: HashMap<String, Question> = HashMap::new();
    questions.insert("billing".to_string(), noul("Is this about billing?").into());
    questions.insert(
        "tone".to_string(),
        choice("What is the tone?", [
            ("calm".to_string(), None),
            ("angry".to_string(), None),
        ].into()).into(),
    );
    questions.insert(
        "urgency".to_string(),
        score("How urgent is this?", vec![
            Some("low".into()),
            Some("medium".into()),
            Some("high".into()),
        ]).into(),
    );

    let response = client
        .system_one("I was charged twice and I need a refund now!", questions)
        .await?;

    if let Some(answer) = response.noul("billing") {
        println!("Billing: {}", answer.noul);
    }
    if let Some(answer) = response.choice("tone") {
        println!("Tone:    {}", answer.choice);
    }
    if let Some(answer) = response.score("urgency") {
        println!("Urgency: {}", answer.score);
    }

    Ok(())
}

Primitives

TypeSafe provides three question types. Ask several in a single request — they run in parallel and share the same state.

Primitive Builder Returns
Noul noul(instructions) noul: f64 — probability of "yes" in [0, 1]
Choice choice(instructions, criteria) choice, probabilities, confidence
Score score(instructions, criteria) score, legend, probabilities, confidence

Noul — yes/no

use typesafeai_sdk::noul;

let q = noul("Does this message convey urgency?");

Choice — pick one option

use typesafeai_sdk::choice;
use std::collections::HashMap;

let q = choice("Which team should handle this?", {
    let mut m = HashMap::new();
    m.insert("billing".to_string(), Some("Payments, refunds".into()));
    m.insert("technical".to_string(), Some("Bugs, outages".into()));
    m
});

Score — rate on a rubric

use typesafeai_sdk::score;

let q = score("How frustrated is the customer?", vec![
    Some("Calm".into()),
    Some("Frustrated".into()),
    Some("Very angry".into()),
]);

Configuration

# use std::time::Duration;
# use typesafeai_sdk::{TypeSafeClient, ClientConfig, RetryPolicy};
# fn main() -> Result<(), Box<dyn std::error::Error>> {
// From environment variables (TYPESAFE_API_KEY, TYPESAFE_BASE_URL, TYPESAFE_DEFAULT_MODEL)
let client = TypeSafeClient::from_env()?;

// Or explicit
let client = TypeSafeClient::new("apikey_...")?;

// Or full control via the builder (ClientConfig is #[non_exhaustive],
// so use ClientConfig::new() and the .with_*() methods):
let config = ClientConfig::new("apikey_...")
    .with_base_url("https://api.typesafe.ai")
    .with_default_model("jev-latest")
    .with_timeout(Duration::from_secs(30))
    .with_retry(
        RetryPolicy::new(3)
            .with_base_delay(Duration::from_millis(500))
            .with_max_delay(Duration::from_secs(10)),
    );
let client = TypeSafeClient::from_config(config)?;

// You can also supply a custom reqwest::Client (e.g. to share a connection
// pool or apply custom TLS settings):
let custom_http = reqwest::Client::builder()
    .timeout(Duration::from_secs(30))
    .build()?;
let config = ClientConfig::new("apikey_...").with_http_client(custom_http);
let client = TypeSafeClient::from_config(config)?;
# Ok(())
# }

Environment variables

Variable Default Description
TYPESAFE_API_KEY — Required. Your API key.
TYPESAFE_BASE_URL https://api.typesafe.ai API base URL.
TYPESAFE_DEFAULT_MODEL jev-latest Default model.

Error handling

All SDK operations return Result<T, TypeSafeError>. Errors map to typed variants:

use typesafeai_sdk::{TypeSafeError, ErrorKind};

match client.system_one(state, questions).await {
    Ok(response) => { /* ... */ }
    Err(e) => match e.kind() {
        ErrorKind::Authentication(msg) => { /* invalid API key */ }
        ErrorKind::RateLimit(msg) => { /* rate limited (after retries) */ }
        ErrorKind::Validation(msg) => { /* invalid questions */ }
        _ => eprintln!("error: {e}"),
    },
}

The SDK automatically retries on 429 Too Many Requests, 529 Overloaded, and 500/502/503/504 server errors, as well as network timeouts and connection failures, with exponential backoff and equal jitter.

Retry safety for POST requests

system_one is a POST request. The SDK retries on transient failures (timeouts, 5xx, 429), but a client-side timeout does not guarantee the server did not process the request. If the endpoint has side effects (credit consumption, usage recording), a retry may result in duplicate processing.

To mitigate this, errors that occur while reading the response body — including timeouts and truncated bodies — are classified as non-retryable so the SDK won't replay a POST whose body the server already received.

Future versions will support an Idempotency-Key header to make retries fully safe.

License

MIT