Provider contracts

Checked on 2026-09-20. This SDK is unofficial.

TypeSafe direct

• POST https://api.typesafe.ai/v1/systemone
• Authorization: Bearer <TYPESAFE_API_KEY>
• Body: model, state, named questions.
• Primitives: choice, noul, score.
• Responses: named answers, resolved model, snake_case token usage.

Sources: HTTP API, models, structured criteria.

Vercel AI Gateway

• POST https://ai-gateway.vercel.sh/v4/ai/evaluation-model
• Authorization: Bearer <AI_GATEWAY_API_KEY>
• ai-gateway-protocol-version: 0.0.1
• ai-gateway-auth-method: api-key
• ai-evaluation-model-specification-version: 4
• ai-model-id: typesafe-ai/jev
• Body: state, named questions; the model travels in a header.

This is the Vercel AI SDK evaluation protocol. It is not Chat Completions, Responses, or a documented stable Java REST API. Protocol changes can require an adapter update. A Vercel key may be valid while the account cannot make requests (for example, payment verification).

Reference implementation pinned to Vercel AI commit 20dd00abba618d5a516e0fee40ccd3e18a2bd1fb:

• Gateway transport and schema
• TypeSafe evaluation mapping
• Official model listing

Meaning	Direct	Gateway	Java
Yes probability	type:noul, noul	type:boolean, probability	NoulAnswer.probability()
Choice	label + probabilities	label + optional probabilities	ChoiceAnswer<T>
Score	weighted level index + legend	weighted level index; legend omitted	ScoreAnswer, request levels supply missing legend
Confidence	answer confidence	providerMetadata.typesafe.confidence[id]	OptionalDouble
Usage	input_tokens, output_tokens	inputTokens, outputTokens	Usage, optional counts

No score normalization, confidence inference, or probability renormalization occurs. Two-decimal display rounding can make probability sums differ slightly from one. Missing/extra answers, mismatched types, unknown labels, invalid level indices, nonnumeric or out-of-range probabilities are protocol failures. Unknown metadata is preserved in the raw response.

OpenRouter (since 0.1.1)

• POST https://openrouter.ai/api/alpha/decisions
• Authorization: Bearer <OPENROUTER_API_KEY>
• Default model: typesafe/jev-1.13; body includes model, state, questions.
• Native noul, choice, and score answers; snake_case input_tokens / output_tokens.
• Choice/Score probabilities and confidence are optional. Score legend, model, usage, response id and provider are optional. Metadata including usage.cost is preserved in the raw response without fabricating missing values.
• Criteria descriptions are string/object/array values; choice also permits null. Score levels cannot be null. Noul criteria need both sides; two null descriptions are encoded as omitted criteria, as in the official provider.

Sources: official Decisions API, official schema at 1b22b05, official mapping. This is an alpha API. OpenRouter live inference has not been tested in this development account; protocol tests use a local HTTP server and fixtures.

URL configuration

baseUrl is an origin with an optional path prefix. The adapter appends its full endpoint suffix (v1/systemone, v4/ai/evaluation-model, or api/alpha/decisions). Do not include that suffix twice. Since 0.1.1, endpoint(URI) / Spring jev.endpoint accepts the complete URL and preserves its path/query without appending anything. The two options are mutually exclusive. The selected client still determines authentication and wire format. User-info and fragments are rejected; baseUrl also rejects queries. Use HTTPS for real API keys; HTTP exists for local servers/proxies.