Getting Started with Jev

Jev is reached through a single endpoint: POST https://api.typesafe.ai/v1/systemone, authenticated with a Bearer key. Official SDKs wrap that call with typed helpers for the three primitives. Everything you send is one state plus a dictionary of questions; everything you get back is one answer per question.

This page covers installation, a first call in TypeScript and Python, the primitives, and the limits worth knowing before you build. Read Prompt Engineering next — most of the quality comes from how you write the questions, not the code.

Install the SDK

npm install @typesafe-ai/sdk

Export your key before you run anything:

export TYPESAFE_API_KEY="your-key"

Your First Decision

A support ticket is a good first state: it has free text, a small set of departments, and a severity that maps to ordered levels. All three primitives fit in one call.

import { TypeSafeClient, noul, choice, score } from '@typesafe-ai/sdk'

const client = new TypeSafeClient({
  apiKey: process.env.TYPESAFE_API_KEY,
  defaultModel: 'jev-1.13.0',
})

const state = {
  ticket_message:
    'My card was charged twice for order A-104. Please refund the duplicate.',
  order: { id: 'A-104', charges: [49, 49] },
  refund_policy: 'Duplicate charges are eligible for a full refund.',
}

const { answers, model, usage } = await client.systemOne({
  state,
  questions: {
    refund_requested: noul('Does `ticket_message` request a refund?'),
    department: choice('Which team should handle this?', {
      billing: 'Charges, invoices, refunds, subscriptions',
      technical: 'Bugs, outages, integration problems',
      other: 'None of the above',
    }),
    severity: score('How severe is the reported issue?', [
      'Cosmetic, no functional impact',
      'Degraded, a workaround exists',
      'Blocking, cannot complete the task',
    ]),
  },
})

console.log(model, usage)
console.log(answers.department.choice, answers.department.confidence)

The Three Primitives

Two consequences of those definitions:

• A Noul at 0.5 means "can't tell," not "medium." To measure a degree, use a Score with described levels instead of tuning a Noul for agreement.
• Score levels are judged independently — the model does not see their neighbors. "Worse than the previous level" is meaningless; each level must describe a concrete situation on its own.

Model Aliases and Version Pinning

GET https://api.typesafe.ai/v1/models lists available models. Today the current model is jev-1.13.0, with two aliases: jev-latest (the stable default) and jev-preview.

Every response reports the versioned ID that answered. Once a threshold matters, request the versioned ID explicitly and log it — tuning against an alias means your thresholds can silently drift when the alias moves.

Limits

Rate limits are adjusted dynamically during early access. The vendor SDKs retry with backoff, which matters because the endpoint returns 429 for rate limits and 529 for overload.

Error Codes

Next Steps

• Prompt Engineering — the question craft that decides whether your integration works
• Confidence Gating — turn probabilities into automated, reviewed, and human paths
• Use Cases — where a decision model earns its place in your stack