---
name: jev-decisions
description: Use when writing or reviewing code that calls Jev (TypeSafe AI's System One model) through the systemone API, the @typesafe-ai/sdk or typesafe_sdk packages, or the jev_* MCP tools; also use when deciding whether a fragile LLM "return JSON" prompt, regex, or if-chain should become a typed Jev question.
---

# Jev decisions

Jev takes a **state** and a map of **typed questions** and returns a typed **answer** per
question, with probabilities. It does not write text, call tools, or chat. Your code asks
narrow questions and decides what to do with the numbers.

Source of truth: https://docs.typesafe.ai/api (this skill follows it as of 2026-09).
Maintained by JEV Hub (https://jevhub.org), an independent community site.

## When to use Jev

Use it when code needs a judgment it can branch on:

- route a request to one of a fixed set of handlers, teams, or models;
- rate something on a rubric (urgency, risk, quality) and threshold the number;
- check whether a statement is true of a document, message, record, or tool call;
- gate an agent action before it has side effects;
- replace an LLM prompt that is asked to "return JSON with a label".

Do **not** use it to generate text, code, summaries, or tool arguments, or for open-ended
answers. Keep the LLM for that and use Jev at the decision points around it.

## The request

```http
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer $TYPESAFE_API_KEY
Content-Type: application/json
```

```json
{
  "model": "jev-latest",
  "state": "Help! My payouts have been failing for 3 days.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "other": null
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": { "true": "Explicitly time-sensitive", "false": "No urgency expressed" }
    }
  }
}
```

- `model`: `"jev-latest"` (moves with releases) or a pinned id such as `"jev-1.13.0"`.
  `jev-preview` also exists. Pin once you have tuned thresholds.
- `state`: a string, or a JSON object/array. Put the evidence here: the ticket, the record,
  the proposed tool call. Refer to nested fields from a question with backticks, e.g.
  ``"Is `proposed_tool_call` destructive?"``.
- `questions`: a **map** from ids you choose to question objects. Answers come back under the
  same ids. The id is not sent to the model, so the question text must stand on its own.
- `instructions` and `criteria` may be strings, objects, or arrays.

### Question types

| type     | criteria                                                       | answer fields                                                                                             |
| -------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `noul`   | optional `{ "true": ..., "false": ... }`                       | `noul`: probability of yes, 0 to 1                                                                        |
| `choice` | required map option -> description or `null`, 2 to 255 options | `choice`, `probabilities` (sum to 1), `confidence`                                                        |
| `score`  | required ordered array, lowest first, 2 to 10 levels           | `score` (float, can land between levels), `legend`, `probabilities` keyed `"0"`, `"1"`, ..., `confidence` |

### Response

```json
{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "other": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}
```

Errors: 401 bad key, 422 invalid body (the body names the field), 429 rate limited,
529 overloaded. Retry 429/529 with exponential backoff; the official SDKs already do.

## SDKs

TypeScript / JavaScript (Node 20+): `npm install @typesafe-ai/sdk`

```ts
import { TypeSafeClient, choice, noul, score } from "@typesafe-ai/sdk";

const client = new TypeSafeClient(); // reads TYPESAFE_API_KEY
const { answers } = await client.systemOne({
  state: { ticket: ticketText },
  questions: {
    team: choice("Which team should handle `ticket`?", {
      billing: "Payments, invoices and refunds",
      technical: "Bugs and integration failures",
      other: null,
    }),
    urgency: score("How urgently does `ticket` need a reply?", [
      "Can wait",
      "Today",
      "Now",
    ]),
    refund: noul("Does `ticket` ask for a refund?"),
  },
});
```

Python: `pip install typesafe-sdk`, then `TypeSafeClient` / `AsyncTypeSafeClient` from
`typesafe_sdk`. Check https://docs.typesafe.ai/sdk/python for the current API.

## Writing good questions

1. One judgment per question. Split "is it urgent and about billing?" into two questions.
2. Put all the evidence in `state`, not in the question text.
3. For Choice, describe each option in `criteria`, and add an `other` option whenever the
   list may not cover every input.
4. For Score, write levels as concrete descriptions, lowest first. Keep the float result;
   `1.4` between two levels is information, not noise.
5. Ask every question about the same state in **one** request. Jev reads the state once;
   batching is much cheaper and faster than one call per question.
6. English is Jev's strongest language. For other languages, test on real data first.

## Deciding in code

- Choice and Score carry `confidence`. The answer says what; confidence says whether to act
  on it alone. Low confidence -> fallback path (ask a human, escalate, use a bigger model).
- Noul has **no** `confidence` field. Threshold `noul` itself (e.g. act above 0.8, ask
  between 0.2 and 0.8).
- If you only need the best option, take `choice`; you do not need a threshold.
- Put questions and threshold constants together in one file so a human can review them.
- Tune thresholds on your own traces. Re-tune when you change the pinned model.

## Using the MCP tools instead

If the JEV Hub MCP server is configured (https://jevhub.org/mcp, endpoint
`https://jevhub.org/api/mcp`, header `Authorization: Bearer <TYPESAFE_API_KEY>`), you can ask
Jev directly while working:

- `jev_noul` {state, question, yes_means?, no_means?} -> probability of yes
- `jev_choice` {state, question, options: [names] or {name: description}} -> choice + probabilities + confidence
- `jev_score` {state, question, levels: [lowest ... highest]} -> score + probabilities + confidence
- `jev_evaluate` {state, questions: <official questions map>} -> all answers

Good uses: before a destructive shell command, ask `jev_choice` with allow / review / block
and stop to ask the user unless it returns allow with high confidence.

## Mistakes to reject in review

| Wrong                                              | Right                                      |
| -------------------------------------------------- | ------------------------------------------ |
| `"model": "systemone"`                             | `"model": "jev-latest"` or `"jev-1.13.0"`  |
| `"questions": [ ... ]`                             | `"questions": { "<id>": { ... } }`         |
| `instruction`, `options`, `labels`, `choices`      | `instructions`, `criteria`                 |
| a `mode` field                                     | does not exist; use each question's `type` |
| `jev-1.13`, `typesafe/jev-1.13`                    | `jev-1.13.0`                               |
| reading `answer.confidence` on a Noul              | read `answer.noul`                         |
| rounding `score` to an integer before thresholding | threshold the float                        |
| one request per question about the same state      | one request, many questions                |
| treating Jev as the agent's chat model             | Jev answers typed questions only           |
