Jev TypeScript API: Choice, Score, and Noul in One Request

Install the SDK and set the API key#

Create a TypeSafe API key, store it outside the repository, and install the official JavaScript SDK:

1
export TYPESAFE_API_KEY='replace-with-your-key'
2
npm install @typesafe-ai/sdk

The SDK reads TYPESAFE_API_KEY and defaults to jev-latest. Pin a version after calibrating production thresholds because the alias can move when TypeSafe releases another model.

The SDK refuses browser execution by default. Calling from a backend route, serverless function, or controlled worker keeps the secret outside client JavaScript.

Ask Choice, Score, and Noul together#

One systemOne request can evaluate several named questions against the same state:

1
import {
2
  choice,
3
  noul,
4
  score,
5
  TypeSafeClient,
6
} from '@typesafe-ai/sdk';
7

8
const client = new TypeSafeClient({
9
  defaultModel: 'jev-1.13.0',
10
});
11

12
const message = {
13
  subject: 'Duplicate March charge',
14
  body: 'My card was charged twice. Please refund it today or I will cancel.',
15
};
16

17
const response = await client.systemOne({
18
  state: message,
19
  questions: {
20
    department: choice('Which team should handle this message?', {
21
      billing: 'Invoices, payments, duplicate charges, and refunds',
22
      technical: 'Service failures, bugs, and integration problems',
23
      sales: 'Pricing, upgrades, and new contracts',
24
      other: 'None of the other options apply',
25
    }),
26
    urgency: score('How urgent is this message?', [
27
      'No deadline or blocking problem',
28
      'Should be handled soon, but no explicit deadline',
29
      'Explicit deadline, operational block, or high churn risk',
30
    ]),
31
    refundRequested: noul('Does the customer explicitly request a refund?', {
32
      true: 'The message directly asks for money to be refunded',
33
      false: 'The message does not request a refund',
34
    }),
35
  },
36
});
37

38
console.log(response.model);
39
console.log(response.answers.department);
40
console.log(response.answers.urgency);
41
console.log(response.answers.refundRequested);

department.choice is the selected label, urgency.score is the probability-weighted rubric level, and refundRequested.noul is the probability of a yes answer. Choice and Score also include distributions and confidence values.

Keep policy decisions in code#

Do not treat the top choice as authorization for an irreversible operation. Apply thresholds and fallback behavior explicitly:

1
const department = response.answers.department;
2
const refund = response.answers.refundRequested;
3

4
if (department.confidence < 0.6) {
5
  await sendToManualReview({ message, reason: 'department_uncertain' });
6
} else if (department.choice === 'billing') {
7
  await enqueueBillingTicket(message);
8
} else {
9
  await enqueueDepartmentTicket(department.choice, message);
10
}
11

12
if (refund.noul >= 0.8) {
13
  await addTicketFlag('refund_requested');
14
}

The values 0.6 and 0.8 are illustrative, not recommended defaults. Choose them from labeled data and the relative cost of false positives, false negatives, and human review.

The refund result should add a signal, not execute the transaction. Order ownership, payment state, amount, authorization, and idempotency still belong to deterministic business logic.

Write questions that can be evaluated#

Keep each question atomic. Do not combine urgency, department, and refund eligibility into one vague score.

• Give Choice options distinct descriptions and include other or none when the catalog is not exhaustive.
• Write Score criteria as ordered, self-contained levels. The API accepts 2 to 10 criteria.
• Use one Noul per independent condition when several labels may be true at the same time.
• Use code for exact dates, totals, and identifiers instead of asking a probabilistic model to reconstruct them.

Choice supports up to 255 options, but a large catalog is not automatically a good single-stage classifier. Evaluate hierarchical routing when neighboring labels become difficult to distinguish.

Define the failure path#

The API can return authentication, validation, rate-limit, or temporary overload errors. The SDK retries selected temporary failures with backoff, but the application still needs a final fallback:

1
try {
2
  const response = await client.systemOne({
3
    state: message,
4
    questions: {
5
      department: choice('Which team should handle this message?', {
6
        billing: 'Billing and payments',
7
        technical: 'Product and integration problems',
8
        other: 'Other requests',
9
      }),
10
    },
11
  });
12

13
  await routeWithPolicy(response.answers.department);
14
} catch (error) {
15
  console.error('TypeSafe decision failed', error);
16
  await sendToManualReview({ message, reason: 'typesafe_unavailable' });
17
}

A support pipeline should usually preserve the ticket by sending it to review. A low-risk recommendation widget may instead use a default order. The product’s failure cost determines the fallback.

Verify in shadow mode before automating#

Run Jev alongside the existing route without changing user-visible behavior. Record the versioned model ID, probabilities, predicted label, actual outcome, latency, and final path. Keep sensitive message text out of uncontrolled logs.

Use that dataset to answer whether English and non-English inputs need different thresholds, which labels overlap, and how often fallback erases the expected savings. Repeat the evaluation before moving from a pinned model to a new release.

Read the Jev model boundary guide before choosing a workflow. If an agent is expected to invoke this API, the Codex routing analysis explains what installing the TypeSafe skill does and does not automate. For local inference, compare Laya’s checkpoints and limits.

FAQ#