TypeSafe's Official JS and Python SDKs, Explained

Most of the projects in this series wrap Jev in something else — an MCP server, a CLI, a benchmark harness. Two don't wrap anything. typesafe-sdk-js and typesafe-sdk-python are TypeSafe's own official client libraries, the layer every other integration in the ecosystem sits on top of. If you've read what Jev is and want to call it directly instead of through someone's MCP server, these are the two implementations to start from.

Both SDKs solve the same problem: send Jev a state — the evidence — and a set of typed questions, get back typed answers keyed by question name. Neither generates prose. The interesting differences are in how each language expresses that contract.

Key Takeaways

• JS SDK is @typesafe-ai/sdk. A TypeSafeClient class with a systemOne() method, ESM, CommonJS and TypeScript declarations, and a choice() helper for defining multiple-choice questions. Requires Node.js 20+.
• Python SDK is typesafe-sdk. A TypeSafeClient used as a context manager (with and async with), with a system_one() method and a Choice question type that takes instructions and a criteria dictionary.
• Type inference is the headline feature in both. The JS SDK infers answer types from the questions you pass; the Python SDK returns a choices dictionary keyed by question name — neither makes you cast or parse raw JSON.
• Both are thin. As of September 2026, JS has 228 stars and Python has 209 — modest by GitHub standards, but expected for SDKs that exist to be invisible plumbing rather than draw attention.
• Auth is identical across both. A single TYPESAFE_API_KEY environment variable, no separate config file.

The JavaScript SDK: @typesafe-ai/sdk

Install it with npm install @typesafe-ai/sdk; it needs Node.js 20 or newer. The package ships ESM, CommonJS and TypeScript declaration files, so it works whether your project is on import or require.

The core API is a TypeSafeClient class with one method that matters: systemOne(). You call it with a state object — whatever evidence the decision needs, a document, a ticket, a transcript — and a questions configuration. The README's canonical example is a support-ticket triage: is this urgent (a probability), which team should own it (a choice from a fixed set). The SDK's choice() function is the helper for defining that second kind of question, and — per the README — answer types are inferred from the questions you write, so a choice() question resolves to the exact literal union you defined rather than a loose string.

Authentication is a single TYPESAFE_API_KEY environment variable. The repository points to TypeSafe's own docs site for the full options reference rather than documenting every parameter inline, and at the time of writing carries no explicit version number or deprecation notices in the README itself — treat it as an actively moving target and pin a version in your lockfile. On aiskill.market: /skills/typesafe-sdk-js-typesafe-ai.

The Python SDK: typesafe-sdk

The Python side mirrors the shape of the JS one but leans into Python idiom. Install with uv add typesafe-sdk (the README leads with uv, though it's installable through standard Python packaging too). TypeSafeClient is used as a context manager — both with TypeSafeClient() as client: and async with are supported, which matters if you're calling Jev from inside an async agent loop rather than blocking it.

The primary method is system_one(), called with a state parameter (the README's example passes document data) and a questions parameter. Where the JS SDK has choice() as a standalone helper, Python defines a Choice question type directly — you hand it instructions plus a dictionary of named criteria (the README's example: "billing", "technical", "other"). The response comes back as a choices dictionary you can index by question name, which is a slightly more manual pattern than the JS SDK's inferred typing but keeps the surface area small.

Like its JS sibling, the Python SDK documents no version pinning guidance or breaking-change policy in the README, and points to docs.typesafe.ai for anything beyond the client and request/response types shown in the source. On aiskill.market: /skills/typesafe-sdk-python-typesafe-ai.

Where these SDKs sit in the ecosystem

Almost every other project in this series either calls Jev's HTTP API directly with its own thin wrapper, or builds on top of one of these two SDKs. effect-agent, covered in jev-align and effect-agent, is a TypeScript project layering the Effect framework's schema and error-handling model on top of a Jev decision provider — the kind of thing that becomes much simpler once @typesafe-ai/sdk handles the raw request shape. On the Python side, projects like jev-skill, covered in simple-jev and jev-skill, ship "stdlib-only" decision wrappers that make an explicit choice not to depend on typesafe-sdk — worth noting if you're picking between a full SDK dependency and a hand-rolled requests call.

If you're building anything non-trivial against Jev directly — as opposed to going through an agent-facing MCP server like the ones covered in wiring Jev into agents with MCP — starting from the official SDK rather than re-implementing the request/response contract is the sensible default. Both repos are MIT-licensed and maintained under the typesafe-ai GitHub organization rather than a third party, and both are listed on the Awesome Jev projects radar.

What isn't documented yet

Neither README states a versioning or stability policy, so treat both as pre-1.0 in spirit even where no explicit beta label is shown. Neither README's example code demonstrates retry behavior, timeout configuration, or streaming — if your integration needs those, check the linked docs site or the source directly before assuming a given method exists. Star counts (228 for JS, 209 for Python as of September 2026) reflect very fresh projects tied to a model that only recently shipped; they're the official SDKs, but "official" here doesn't yet mean "battle-tested at scale" — nobody outside TypeSafe has published production numbers on either one.

What to do next

1. Pick the SDK matching your runtime, not the one with marginally more stars — 228 vs. 209 is noise at this project age.
2. Read the linked docs site before you assume a feature exists. Both READMEs are intentionally thin and defer detail to typesafe.ai's docs and the source's type definitions.
3. Pin a version. With no stated stability policy, floating on latest in either package manager is a bet you should make deliberately.
4. If you're already inside Effect or a similarly typed framework, look at effect-agent before wrapping the raw SDK yourself — someone has likely already built the adapter you need.
5. Compare against the wider field. Browse the full project list at the Awesome Jev projects radar and see jevbench and the other benchmarks for how Jev itself performs, separate from any SDK's ergonomics.