Jev Python SDK (TypeSafe AI): a version-pinned call, timeouts, retries and missing-key errors
The official Python package is typesafe-sdk, imported as typesafe_sdk. This page gives a minimal SDK call, the same request as raw HTTP, a standard-library client with bounded retries, and the twelve mistakes that most often produce a 400 or 422 error.
Install typesafe-sdk 0.7.5 (uploaded 14 Oct 2026; adds experimental image and Box types). Defaults, as read at 0.7.4: 10 s timeout, 2 retries on 408/429/5xx within 30 s; a missing key raises TypeSafeError when the client is created. Documented package read 14 Oct 2026; 0.7.5 read 16 Oct 2026; 0.7.5 still the latest on 7 Nov 2026 (R27-S25)
Python 3.10 or later. Call TypeSafeClient().system_one(state=…, questions=…, model="jev-1.13.0"). Choice, Score and Noul are classes in typesafe_sdk. Pin jev-1.13.0 rather than the default alias jev-latest. The package called typesafe-ai on PyPI is not TypeSafe's. Documented SDK docs, PyPI and GitHub, checked 28 Sep 2026
Checked at typesafe-sdk 0.7.5 (16 Oct 2026) (uploaded to PyPI 14 Oct 2026, 21:21 UTC; a patch over 0.7.4). It adds image and Box types: the package exports Image, Asset, Box, BoxAnswer and BoxCoordinates (typesafe_sdk/__init__.py L5, L27-43; _core/question_types.py L142 class Box). The default model is still jev-latest (constants.py L18), which on 23 Oct 2026, 05:45 UTC, still pointed to jev-1.13.0; TypeSafe said on 14 Oct 2026 that it would move to jev-1.14.0 "in a week" and has published no date for the move (R17-S09, R22-S05). Update, 24 Oct 2026: the default jev-latest (constants.py L18) on TypeSafe's API pointed to jev-1.14.0 on 24 Oct 2026, 05:12 UTC (it pointed to jev-1.13.0 until at least 23 Oct 2026, 05:45 UTC). Pin jev-1.13.0 if your thresholds were tuned on 1.13. The package version is unchanged (0.7.5 on PyPI, 24 Oct 2026, 05:18 UTC), so the L18 pin still applies (R23-S05, R23-S41). Checked again on 30 Oct 2026, 05:21 UTC: typesafe-sdk is still 0.7.5 on PyPI, and the release feed's latest is still v0.7.5 (14 Oct) (R24-S36, R24-S39). On 16 Oct 2026, 05:21 UTC, jev-latest pointed to jev-1.13.0 and jev-preview to jev-1.14.0 (since 14 Oct) (R17-S05). No TypeSafe-Danger-Zone-Images header string was found in the wheel's files, so the package does not set the image opt-in header itself; you send it yourself. Read again on 23 Oct 2026 at 0.7.5: the SDK does not check image format or size; it sends what you give it and the API returns 400 or 413. You add the opt-in header yourself (_core/assets.py L24–28; R22-S109). Images and Box are experimental and not production-ready per TypeSafe. Failure paths were last read at 0.7.4 and 0.6.0. For this Python package the failure path (timeouts, retries, exception classes) was last read at 0.7.4 and not re-read at 0.7.5; 0.6.0 is the TypeScript SDK read. Read 16 Oct 2026, 05:25 UTC, from the published wheel; nothing was installed or run. The examples stay pinned at 0.7.4, where their call surface was read. Documented R17-S37 (PyPI and wheel), R17-S05 (models page), R17-S09 (TypeSafe post)
Change, 30 Oct 2026: version recheck added; typesafe-sdk is still 0.7.5 (PyPI and release feed, 05:21 UTC; R24-S36, R24-S39). Nothing else on this page was re-read.
Change, 24 Oct 2026: the default-alias sentence adds the 24 Oct check: on TypeSafe's API jev-latest pointed to jev-1.14.0 (first seen 05:12 UTC), so the SDK's default now gives 1.14 there; the version is still 0.7.5 (R23-S05, R23-S41).
Change, 23 Oct 2026: the default-alias sentence now gives the 23 Oct check (jev-latest still on jev-1.13.0, no date published for the move); the image sentence now says the SDK does not check image format or size (read at 0.7.5). How other SDKs and integrations handle images: Jev with images: does your SDK or integration send them?
Change, 16 Oct 2026: current version 0.7.4 → 0.7.5, which adds experimental image and Box types; the default model is still jev-latest, but TypeSafe says that alias will move from jev-1.13.0 to jev-1.14.0 about a week after 14 Oct, so pin jev-1.13.0 if you need stable answers. Defaults, retries and exception classes on this page are as read at 0.7.4.
Earlier version checks (5, newest first)
- 14 Oct 2026: Checked at typesafe-sdk 0.7.4 (released 9 Oct 2026, 15:47 UTC; Python 3.10 or later; extra
http2). Defaults: key fromTYPESAFE_API_KEY; base URLhttps://api.typesafe.ai; modeljev-latest; timeout 10 s per HTTP operation;max_retries2 on 408, 429 and 5xx, within a 30 s total retry budget. A missing key raisesTypeSafeErrorwhen the client is created. Read 14 Oct 2026 from the published package (nothing installed or run). Documented R16-S200 (PyPI), R16-S201 (constants), R16-S202 (retry), R16-S203 (errors, config), R16-S204 (client, exports) Change, 14 Oct 2026: current version 0.7.2 → 0.7.4; the example pins move to 0.7.4 (the call surface they use was read at 0.7.4); defaults, exports and exception classes unchanged; new page title. - 11 Oct 2026: defaults read from the 0.7.4 wheel (nothing installed) matched the 0.7.2 defaults on this page: 10.0 s per HTTP operation,
max_retries2 with a 30 s total retry budget, retries on 408, 429, 5xx, connection errors and timeouts; a timeout raisesTypeSafeAPITimeoutError(a subclass ofTypeSafeErrorand ofTimeoutError) (R13-S300 to R13-S304). - 10 Oct 2026, 05:12 UTC: typesafe-sdk 0.7.3 and 0.7.4 published on 9 Oct 2026 (patches), not yet re-audited (R12-S34).
- 30 Sep 2026, 20:47 UTC (also 29 Sep, 07:07 UTC): PyPI still listed 0.7.2 as the latest release.
- 28 Sep 2026: page audited at 0.7.2.
How these examples were checked. The SDK and curl examples are copied from TypeSafe's documentation with the model pinned; the pool did not run them (its offline install failed and it has no API key). The standard-library retry client was run by the pool against a local mock server only, not against the Jev API. Before you start, check whether you can get a key today.
Package facts
- Package
typesafe-sdk(importtypesafe_sdk)- Current version
- 0.7.5, uploaded 14 Oct 2026, 21:21 UTC (checked 16 Oct 2026; R17-S37; still the latest on 24 Oct 2026, 05:18 UTC, R23-S41, and on 30 Oct 2026, 05:21 UTC, R24-S36). Defaults and failure path below read at 0.7.4
- Images and Box
- Exports
Image,Asset,Box,BoxAnswer,BoxCoordinatesfrom 0.7.5; experimental, not production-ready per TypeSafe; the package does not send theTypeSafe-Danger-Zone-Images: trueopt-in header itself (add it withextra_headers) and does not check image format or size (read 23 Oct 2026; R22-S109) - Install
pip install typesafe-sdkoruv add typesafe-sdk;[http2]extra since 0.7.2- Python
- 3.10 or later
- Licence and code
- MIT; typesafe-ai/typesafe-sdk-python
- Defaults
- Base URL
https://api.typesafe.ai; modeljev-latest(what it points to); timeout 10 s per HTTP operation;max_retries2 on 408, 429 and 5xx within a 30 s budget - Missing key
- Raises
TypeSafeErrorat client creation (_core/config.pyL34); the error reaches the caller:fail-closedunless the caller catches it
Release history: 0.5.7 (first public; PyPI 11 Sep, while TypeSafe's release notes say 12 or 14 Sep), 0.6.0 (15 Sep), 0.7.0 (18 Sep, move to Pydantic), 0.7.1 (21 Sep), 0.7.2 (26 Sep), 0.7.3 and 0.7.4 (both 9 Oct), 0.7.5 (14 Oct, 21:21 UTC; R17-S37). The vendor changelog's newest entry is v0.7.3 (9 Oct: a TLS crash fix, more request validation, pooled connections kept alive 30 s); it has no 0.7.4 entry, although 0.7.4 is on PyPI (changelog as served 14 Oct 2026, 16:49 UTC; R16-S205). Sources: PyPI, changelog.
1. Minimal SDK call: Choice, Score and Noul
Documented Adapted from the official quickstart; only the model and package are pinned and answers are read through the SDK's accessors. The call surface it uses (constructor, system_one, the three question classes) was read in the 0.7.4 package on 14 Oct 2026. Not executed by the pool.
Jev's question types on TypeSafe's models page (7 Nov 2026): Choice, Score and Noul on both versions; Box (bounding box in an image) on Jev 1.14 only, behind the images opt-in header (models page "Question types" row and quickstart; R27-S05, R27-S03). This example covers Choice, Score and Noul; typesafe-sdk 0.7.5 adds experimental image and Box types (read 16 Oct 2026), which are not used here.
# pip install "typesafe-sdk==0.7.4" # requires Python >= 3.10
# export TYPESAFE_API_KEY=... # from console.typesafe.ai
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
ticket = "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP."
with TypeSafeClient() as client:
response = client.system_one(
state=ticket,
questions={
"department": Choice(
instructions="Which team should handle this",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"frustration": Score(
instructions="How frustrated the customer appears",
criteria=["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"],
),
"is_urgent": Noul(instructions="The message conveys urgency or time-sensitivity"),
},
model="jev-1.13.0", # pin; the default "jev-latest" is an alias that moves on new releases
)
print(response.model) # versioned ID that answered, e.g. "jev-1.13.0"
print(response.choices["department"].choice, response.choices["department"].confidence)
print(response.scores["frustration"].score) # may fall between levels
print(response.nouls["is_urgent"].noul) # probability of "yes"; no confidence field
2. The same request as raw HTTP
Documented Official quickstart. Not executed by the pool.
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Help! My payouts have been failing for 3 days.",
"model": "jev-1.13.0",
"questions": {
"department": {"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"billing": "Payments, invoicing, refunds",
"technical": "Bugs, outages, integrations",
"sales": "Pricing, upgrades, new accounts"}},
"is_urgent": {"type": "noul", "instructions": "Does this convey urgency?"}
}
}'
What comes back
| Field | Type | Meaning |
|---|---|---|
model | string | The versioned model that answered (for example jev-1.13.0), even when you sent an alias. Log it. |
answers.<id>.type | choice, score or noul | Matches the question type. |
Choice: choice, probabilities, confidence | string; option → number (sums to 1); number 0–1 | choice is documented as the highest-probability option (see gotcha G7). confidence is not the probability of being right; see confidence thresholds. |
Score: score, legend, probabilities, confidence | number; level index → text; level → number; number | score is probability-weighted and "can land between levels". |
Noul: noul | number 0–1 | Probability of yes. No confidence field. |
usage.input_tokens, usage.output_tokens | integer | Both are returned; only input tokens are billed on TypeSafe direct. See cost per decision. |
Header x-typesafe-request-id | string | Exposed by the SDK as request_id on results and errors. Include it in support requests. |
3. Standard-library client with bounded retries
Tested (offline, local mock server, no Jev call) Python 3.11.2, 28 Sep 2026. Retry set, backoff, Retry-After handling, 10 s timeout and 30 s budget copy the official SDK defaults. The same test for Node (T04), with the branches to cover, is on Testing without a key.
# Raw-HTTP Jev call with bounded retries (standard library only).
# Checked against docs.typesafe.ai/api (2026-09-28). Not run against the live API.
import json, os, random, time, urllib.request, urllib.error
API_URL = os.environ.get("TYPESAFE_BASE_URL", "https://api.typesafe.ai") + "/v1/systemone"
RETRY_STATUSES = {408, 429, *range(500, 600)} # same set as the official Python SDK default (includes 529)
class JevError(Exception):
def __init__(self, status, body):
super().__init__(f"{status}: {body[:200]}")
self.status, self.body = status, body
def _backoff(attempt): # 0.5 s, 1 s, 2 s ... capped at 5 s, minus up to 25% jitter
return min(5.0, 0.5 * 2 ** attempt) * (1 - random.random() * 0.25)
def _server_delay(h): # honour retry-after-ms, then retry-after (seconds only)
ms, s = h.get("retry-after-ms"), h.get("retry-after")
if ms and ms.replace(".", "", 1).isdigit():
return float(ms) / 1000
if s and s.isdigit():
return float(s)
return None
def ask_jev(state, questions, model="jev-1.13.0", max_retries=2, timeout=10.0, budget=30.0):
body = json.dumps({"state": state, "model": model, "questions": questions}).encode()
headers = {"Authorization": "Bearer " + os.environ["TYPESAFE_API_KEY"].strip(),
"Content-Type": "application/json"}
start = time.monotonic()
for attempt in range(max_retries + 1):
req = urllib.request.Request(API_URL, data=body, headers=headers, method="POST")
try:
with urllib.request.urlopen(req, timeout=timeout) as resp:
return json.load(resp)
except urllib.error.HTTPError as e:
status, text = e.code, e.read().decode("utf-8", "replace")
if status not in RETRY_STATUSES or attempt == max_retries:
raise JevError(status, text) # 400/401/403/404/422: fix the request or key, do not retry
delay = _server_delay(e.headers) or _backoff(attempt)
except (urllib.error.URLError, TimeoutError): # network error or timeout
if attempt == max_retries:
raise
delay = _backoff(attempt)
if time.monotonic() - start + delay >= budget:
raise JevError(0, "retry budget exhausted")
time.sleep(delay)
Results against the local mock server: a 429 with Retry-After: 1 followed by a 200 succeeded on the second attempt after 1.01 s; three 529 responses in a row gave up after 3 attempts; 400, 403 and 422 returned after one attempt with no retry. The live API's headers were not observed. This client does not tell a Cloudflare HTML 403 apart from a key 403: check the response Content-Type before rotating keys (see errors and rate limits).
4. SDK error handling
Documented Exception classes and RetryPolicy checked against the SDK's __all__ at tag v0.7.2; exports and exception classes unchanged in the 0.7.4 package (read 14 Oct 2026). Not executed by the pool.
from typesafe_sdk import (TypeSafeClient, RetryPolicy, TypeSafeAPIError, TypeSafeRateLimitError,
TypeSafeBadRequestError, TypeSafeUnprocessableEntityError,
TypeSafeAuthenticationError, TypeSafePermissionDeniedError,
TypeSafeAPITimeoutError)
client = TypeSafeClient(retry=RetryPolicy(max_retries=2, timeout=30.0)) # these are the defaults
try:
r = client.system_one(state, questions, model="jev-1.13.0")
except (TypeSafeBadRequestError, TypeSafeUnprocessableEntityError) as e: # 400 / 422: fix the request
log_and_fallback(e.status, e.body, e.request_id)
except (TypeSafeAuthenticationError, TypeSafePermissionDeniedError) as e: # 401 / 403 (see error matrix)
log_and_fallback(e.status, e.body, e.request_id)
except (TypeSafeRateLimitError, TypeSafeAPITimeoutError, TypeSafeAPIError) as e:
fallback_after_retries_exhausted(e) # SDK already retried 408/429/5xx
Mistakes that cause 400 and 422 errors, and other gotchas
| # | Symptom | Cause | Fix | Source and status (28 Sep) |
|---|---|---|---|---|
| G1 | TypeError from msgspec after upgrading | 0.7.0 moved serialisation from msgspec to Pydantic | Call .model_dump() before handing answers to another JSON layer | #16, closed as intended; no fix version Documented |
| G2 | 422 "Field required" for body.state | state=None is sent as JSON null | Always send a string, object or array | #17, open Reported |
| G3 | 400 "Noul question must have criteria or instructions" | A Noul() with neither instructions nor criteria passes SDK validation | Always give instructions | #17, sdk-js #6, skills #1, open Reported |
| G4 | 400 on every question in hand-built JSON | "type": "Noul" capitalised; the API accepts lowercase only | Use noul, choice, score | oh-my-claudecode #4091; not an SDK bug Reported |
| G5 | 422 list_type on Score criteria | Criteria sent as a map; SDK 0.6.0 and later require an ordered list | Send a list, lowest level first | Changelog 0.6.0; #4091 Documented |
| G6 | An empty Choice is sent without a local error | The SDK checks empty Score criteria but not empty Choice criteria | Check len(criteria) >= 1 yourself | #12, open Reported |
| G7 | choice is 0.01 below another option's probability | Near-ties: probabilities are rounded to two decimals after the winner is picked | Compute the argmax from probabilities if it matters; send such cases to review | #15, open; maintainer: "a problem in our API" Reported |
| G8 | API key appears in exception text | 0.7.0 used a key with a trailing newline as-is | Upgrade to 0.7.1 or later | #9, fixed in 0.7.1 Documented |
| G9 | Oversized questions come back as an error | The SDK does not check the 255-option or 10-level maxima | Check len(options) <= 255 and 2 <= len(levels) <= 10 before sending | SDK source _core/questions.py Documented |
| G10 | Answers change with no code change | The default jev-latest alias moves to new releases | Pin model="jev-1.13.0" and log response.model (what to pin on each route) | Models page Documented |
| G11 | Customer text appears in logs | With TYPESAFE_LOG_LEVEL=debug, request and response bodies are logged and "not redacted" | Do not use debug logging on production data | SDK usage page Documented |
| G12 | pip install typesafe-ai seems to work | That package is a third-party shim that pulls in typesafe-sdk | Install typesafe-sdk directly | PyPI metadata; still 0.1.0 only, its summary calls it a "Redirect shim" (14 Oct 2026, R16-S206) Documented |
Docs inconsistency: TypeSafe's jaggedness page builds a client with model="jev-1.13", which the Models page does not list. An unknown model is reported to return 400. Whether jev-1.13 is accepted was not tested; use jev-1.13.0.
Using the SDK through a gateway
The SDK can point at another base URL if that service follows TypeSafe's API. A gateway model ID does not tell you which versioned model answered, so log response.model. Prices and terms for each route are on Where to use Jev. Documented SDK usage page, 28 Sep 2026
| Route | base_url | model | Key variable in the official example |
|---|---|---|---|
| TypeSafe direct | https://api.typesafe.ai (default) | jev-1.13.0 | TYPESAFE_API_KEY |
| OpenRouter | https://openrouter.ai/api | typesafe/jev-1.13 (recommended: pins the minor version); ~typesafe/jev-latest is the moving alias. See model IDs and aliases | OPENROUTER_API_KEY |
| Vercel AI Gateway | https://ai-gateway.vercel.sh/typesafe | typesafe-ai/jev | AI_GATEWAY_API_KEY |
| Pydantic AI Gateway | https://gateway-us.pydantic.dev/proxy/typesafe | jev-latest | PYDANTIC_AI_GATEWAY_API_KEY |
Which model IDs and aliases each route accepts, and where you can pin a version (6 Oct 2026): Jev model IDs and aliases by route.
Conflict, 5 Oct 2026: the Pydantic AI Gateway row is taken from TypeSafe's SDK usage page (28 Sep). The gateway's own documentation lists OpenAI, Anthropic, Google Vertex, Groq and Bedrock ("More providers coming soon"), and providers/gateway.py in pydantic-ai v2.54.0 has no TypeSafe entry, so the pool found no sign that it routes Jev today (framework integrations). Documented both sides; not tested.
Other Python projects that are not the official SDK
- Simon Willison's
llm-typesafe0.1a0 (22 Sep 2026, alpha) is a plugin for thellmcommand-line tool. - "Jev in 25 lines of Python" (nobodywho) is a local Jev-like model built on Qwen3-0.6B. It is not a TypeSafe client and does not call Jev.
- For Python videos, see the Python group on the videos page.
What was not verified
- No example on this page was run against the Jev API; the pool has no key.
- The SDK itself was not installed or executed: the offline install failed because the sandbox's temporary directory does not allow execution.
- The 0.7.4 package was read as files on 14 Oct 2026 (constants, retry, errors, config, client and exports); nothing was installed, imported or run.
- The 0.7.5 wheel was read as files on 16 Oct 2026 (exports, question types, constants, and a search for the image opt-in header); nothing was installed or run. Its timeout, retry and error path was not re-read, and no image or Box question was sent.
- Status codes in the gotchas table come from named third-party reports with dates; TypeSafe may have changed behaviour since.