# typesafeai-sdk
[](https://crates.io/crates/typesafeai-sdk)
[](https://docs.rs/typesafeai-sdk)
[](https://github.com/Ketankhunti/typesafe-sdk-rust/blob/main/LICENSE)
Rust SDK for [TypeSafe AI](https://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
```toml
[dependencies]
typesafeai-sdk = "0.4"
```
> Requires Rust 1.88+ and uses `rustls-tls` (no OpenSSL dependency).
## Quickstart
Set your API key:
```bash
export TYPESAFE_API_KEY=apikey_...
```
Ask a question:
```rust,no_run
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.
| **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
```rust
use typesafeai_sdk::noul;
let q = noul("Does this message convey urgency?");
```
### Choice — pick one option
```rust
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
```rust
use typesafeai_sdk::score;
let q = score("How frustrated is the customer?", vec![
Some("Calm".into()),
Some("Frustrated".into()),
Some("Very angry".into()),
]);
```
## Configuration
```rust,no_run
# 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
| `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:
```rust,ignore
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