jev quickstart

Start with One Bounded Decision

A useful first call is not “understand this ticket.” It is one operational question with a known answer shape: choose an approved queue, measure one yes/no condition, or rate against explicit ordered levels. The primitive decision guide separates Choice, Noul and Score; Choice versus Noul prevents forced single-label designs.

The examples below follow TypeSafe’s official READMEs and API reference as checked September 22, 2026. They are source-verified, not live API executions in this repository because no TypeSafe credential is available here. Before deployment, run the chosen client against your account, pin package versions and capture a sanitized response fixture.

Python: Official Client and Typed Choice

The official README demonstrates Choice, TypeSafeClient, the context-manager lifecycle and system_one. This version pins the model and keeps the full Choice answer rather than logging only the winning label. Confirm the exact installed SDK types because client releases can evolve independently of this article.

# uv add typesafe-sdk
from typesafe_sdk import Choice, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state={"document": "I was charged twice. Please fix this ASAP."},
        questions={
            "category": Choice(
                instructions="What is this ticket about?",
                criteria={
                    "billing": None,
                    "technical": None,
                    "other": None,
                },
            ),
        },
        model="jev-1.13.0",
    )

answer = response.choices["category"]
print(answer.choice)
print(answer.probabilities)
print(response.model, response.usage)

TypeScript: Keep the Client on the Server

The official JavaScript SDK requires Node 20 or newer and infers answer types from the questions object. Its source refuses browser use by default because that would expose the API key. Put the client in a server route, worker or trusted backend; a framework environment variable prefixed for public/browser use is not a secret.

// npm install @typesafe-ai/sdk
import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({ defaultModel: "jev-1.13.0" });
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);
console.log(response.answers.category.probabilities);
console.log(response.model, response.usage);

HTTP: The Smallest Portable Contract

The API returns model, answers keyed by the caller’s question IDs, and usage with input and output token counts. A Noul answer contains type and noul; Choice and Score carry their own fields and confidence. Validate the discriminated answer type before reading it, and do not turn transport success into a pass/fail decision automatically.

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13.0",
    "state": "I was charged twice. Please fix this ASAP.",
    "questions": {
      "is_refund_request": {
        "type": "noul",
        "instructions": "Does the customer explicitly ask for a charge to be reversed?"
      }
    }
  }'

Put a Production Boundary Around the Call

Make the First Test Useful

A successful curl proves authentication and schema, not evaluator quality. Follow Jev calibration and threshold selection before using a probability to automate an action. Review Jev 1.13 limitations for fixtures around arithmetic, dates, indirection, long state and adversarial content.

1. Create 30–100 representative fixtures, including no-match, ambiguous and adversarial cases.
2. Have a domain owner label them without seeing Jev’s answer.
3. Run a pinned model and save complete serialized responses.
4. Report class errors, calibration, latency, usage and failure behavior.
5. Choose thresholds on separate calibration examples, then shadow before acting.

Quickstart Mistakes That Survive into Production