Crate openkind_client

Expand description

openkind-client: an async Rust client for the openkindd daemon and the TypeSafe Jev SystemOne HTTP API, including OpenRouter’s System One route. Cloudflare Workers AI uses the same question types via ClientBuilder::cloudflare_account.

Built directly on the openkind-core wire types. Successful evaluation responses are validated against their originating requests, including question types and Choice keys. Wire-compatible with https://api.typesafe.ai and the typesafe_sdk Python SDK: the same retry taxonomy, Retry-After handling, error envelope parsing, request ids, and env-var resolution — with defaults mirroring the Python RetryPolicy (2 retries, 0.5s→5s exponential backoff, 25% jitter, 408/429/5xx retried, 30s total budget).

§Quick start

use openkind_client::{question, Client};

let client = Client::builder()
    .api_key("dev-key")
    .base_url("http://127.0.0.1:18080")
    .build()?;

let response = client
    .system_one(
        "I was charged twice. Please help.",
        [
            ("billing", question::noul("Is this about billing?")),
            (
                "tone",
                question::choice("What is the tone?", [("calm", None), ("angry", None)]),
            ),
        ],
    )
    .await?;

let billing = match &response.answers["billing"] {
    openkind_client::Answer::Noul(answer) => answer.noul,
    _ => unreachable!(),
};
println!("billing probability: {billing}");

§Rate limiting, overload, and retries

429 (rate_limited) and 529 (overloaded) responses carry retry-after-ms / Retry-After headers. The client reads them and waits exactly as long as the server asked, falling back to exponential backoff with jitter for other transient failures (408, 5xx, connection errors, timeouts). See RetryPolicy to tune or disable.

§Errors

All failures surface as Error; server rejections as Error::Api with the status, error code, message, x-typesafe-request-id, and parsed retry_after. See error.

§Environment variables

Builder option	Primary	Python-SDK fallback
`api_key`	`OPENKIND_API_KEY`	`TYPESAFE_API_KEY`
`base_url`	`OPENKIND_BASE_URL`	`TYPESAFE_BASE_URL`
`default_model`	`OPENKIND_DEFAULT_MODEL`	`TYPESAFE_DEFAULT_MODEL`

Explicit builder values win; empty/whitespace env values are ignored.

Re-exports§

pub use client::Client;
pub use client::ClientBuilder;
pub use client::Health;
pub use client::IntoState;
pub use client::RequestOptions;
pub use client::DEFAULT_BASE_URL;
pub use client::DEFAULT_MODEL;
pub use client::DEFAULT_TIMEOUT;
pub use client::MAX_RESPONSE_BODY_SIZE;
pub use error::ApiError;
pub use error::ApiErrorKind;
pub use error::Error;
pub use retry::RetryPolicy;

Modules§

client: Async HTTP client implementation, builder, and request options. The async Client for the openkind / TypeSafe SystemOne HTTP API.
error: Client error types, envelope extraction, and status classifications. Error taxonomy and header parsing for the client, mirroring the TypeSafe Python SDK exception hierarchy:
question: Question construction convenience helpers. Ergonomic constructors for Question and State wire types.
retry: Retry policy, exponential backoff, and jitter strategies. Retry policy with exponential backoff and Retry-After support, mirroring the TypeSafe Python SDK’s tenacity-based RetryPolicy defaults: 2 retries, 0.5s initial backoff doubling to a 5s cap, 25% subtractive jitter, retrying 408/429/5xx (including the 529 overload status) plus connection and timeout errors, within a 30s total budget per call.

Structs§

ChoiceAnswer: probabilities is a full distribution (sums to 1) over the criteria keys. confidence is required (per spec). f64 for wire-format precision.
ChoiceQuestion: Pick one option from a set. Spec: https://docs.typesafe.ai/api#choice
ModelInfo: One entry in the models array. Fields are required and order-stable.
ModelsResponse: Top-level GET /v1/models response.
NoulAnswer: Spec: noul is a number 0..1. No confidence field — Noul answers don’t get one per the spec.
NoulCriteria: Reserved true/false keys. r#true / r#false because those are keywords in Rust (and in the JSON spec).
NoulQuestion: Yes/no question. Returns the probability the answer is yes.
ScoreAnswer: legend is level-index (string) → level description. probabilities is keyed by the same index strings. confidence required. f64 for wire-format precision.
ScoreQuestion: Rate along an ordered rubric. Spec: https://docs.typesafe.ai/api#score
SystemRequest: Evaluation request payload representing a Jev-compatible System 1 judgment query.
SystemResponse: Evaluation response payload containing answers to all submitted questions.
Usage: Token usage accounting for the evaluation request.

Enums§

Answer: Tagged union of answer models matching the evaluated question types.
Question: Tagged union of the three question kinds. The type field is the discriminant.
State: State to evaluate. Permissive JSON shape: any string, object, or array.

Constants§

API_VERSION: Wire API version. Bumped on any breaking schema change.