Daily Use: Master the Five Ways to Ask Jev
💡 Goal: In about 1 hour, master everyday Jev usage—feed the right material (state), ask the right questions (Choice / Score / Noul / Box), read the confidence in the answers, and turn every answer directly into a branch of your code.
🎯 Stage Goals
- Write state in three forms based on the shape of your material (string / JSON object / text array), and use dot paths to point questions at specific fields
- Given any decision requirement, be able to pick the right question type—Choice, Score, Noul, or Box—and name the fields in the answer
- Set thresholds using confidence and Noul probability: which answers to execute automatically, which to flag for review, and which to escalate to a human
⏳ Estimated Time
- 6 lessons totaling about 58 minutes, roughly 41–75 minutes with buffer
- Each lesson stands on its own and can also be read individually; 2.1 State is the foundation for the other five lessons, so we recommend starting there
🚀 Before You Start
- completed installation and the first request:
route_ticket.pystill runs,TYPESAFE_API_KEYis in your environment variables (readers starting from scratch should first see the quick start guide) - know that Jev only makes structured decisions and does not generate text—if you haven't read it yet, spend 8 minutes on What is Jev
- no need to open a terminal: paste your state and add questions in the TypeSafe Playground (
console.typesafe.ai/playground) for a code-free experience - a cup of water ☕—this stage is mainly about building a feel for it, and the code in each lesson is short
📚 Lessons in This Stage
A single Jev request has only two things: state (the material to judge) + questions (typed questions). You already sent one request in the quick start stage; this stage turns "how to ask" into muscle memory—lesson 1 covers feeding material, and the following 5 lessons cover each of the five ways to ask.
First, the big picture. There are four question types in questions: Choice (selection), Score (rating), Noul (yes/no), and Box (image localization); the confidence that comes with the answer tells you how certain the judgment is. Four question types + confidence are the five ways to ask you need to master for daily use, each with its own lesson:
| Way of Asking | What It Answers | What's in the Answer |
|---|---|---|
| Choice multiple-choice | which one to pick from fixed options | choice, probabilities (probability for each option), confidence |
| Score rating | which level it lands on in the ordered scale you define | score (can land between two levels, e.g. 0.67), legend, probabilities, confidence |
| Noul yes/no | the probability that this judgment is true | noul (0–1; no separate confidence) |
| Confidence confidence | how certain this answer is | a single number in 0–1; included with Choice / Score / Box answers, not with Noul |
| Box image localization | where the target is in the image | box (four edges—top / bottom / left / right—each 0–1) + confidence |
How to choose? The official selection advice is just four lines:
- The answer is a set of known options → Choice (if the list may be incomplete, add an
otherornone of the aboveoption) - The answer lies on a spectrum where every level can be described → Score
- A clean yes/no judgment where the probability itself is useful → Noul (0.5 is "fifty-fifty" uncertainty, not "medium degree"—to measure degree, use Score)
- Finding something in an image → Box (experimental feature: the official docs state that Images / Box has not yet reached production standards, and the format may change between versions)
When both question types fit, choose the one whose answer can be acted on directly by code: Choice maps to a few code branches, Score maps to a threshold, and Noul maps to a single if.
Lesson schedule:
| Lesson | Content | Duration |
|---|---|---|
| 2.1 State | how to choose among the three forms of state, organize tickets into structured JSON, use dot paths to point questions at specific fields, and trim material within context limits | 8 minutes |
| 2.2 Choice questions | Give all options in criteria, read the probabilities of each option, and add an other option when the list is incomplete | 10 minutes |
| 2.3 Score questions | Define an ordered scale, read the score that can land between two levels, and split complex judgments into multiple questions weighted and merged in code | 10 minutes |
| 2.4 Noul yes/no questions | How to read 0–1 probabilities, 0.7 / 0.3 starting thresholds, and how to choose between it and Score | 8 minutes |
| 2.5 Confidence | How confidence is computed from a probability distribution, the three-tier usage (auto-execute / flag for review / escalate to human), and thresholds that scale with risk | 12 minutes |
| 2.6 Box and images | Put images into state and questions, Box returns four edge ratios, and Danger Zone request headers and Image support in the Python SDK | 10 minutes |
A quick look first: one request mixing three kinds of questions
Question types can be freely mixed; all questions are evaluated in parallel and independently against the same state—adding questions barely increases response time, only costing the tokens for a few extra questions. This example from the official documentation asks one yes/no, one choice, and one score question at once:
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
state = {
"ticket_message": "My flight was cancelled. Can I get a refund?",
"refund_policy": "Cancelled flights are eligible for a full refund.",
}
with TypeSafeClient() as client:
response = client.system_one(
state=state,
questions={
"refund_requested": Noul(
instructions="Does `ticket_message` request a refund?",
),
"request_type": Choice(
instructions="What is the main request in `ticket_message`?",
criteria={
"refund": "The customer wants money returned.",
"rebooking": "The customer wants a replacement flight.",
"information": "The customer is asking for information only.",
},
),
"frustration": Score(
instructions="How frustrated does the customer appear in `ticket_message`?",
criteria=[
"Calm and neutral.",
"Concerned but civil.",
"Very angry or using strong language.",
],
),
},
)
print(response.answers["refund_requested"].noul)
print(response.answers["request_type"].choice)
print(response.answers["frustration"].score)Each of the three answers is a typed value: a probability, an option name, a score—in code you can directly if without parsing generated text.
⚠️ Test Chinese-language material before going live
The main training language of Jev is English, so accuracy is best with English material; other languages such as Chinese work but with lower accuracy. Before going live with Chinese content, run a round of testing on your own data, focusing on confidence.
🎒 What you will gain
- An intuition for designing questions: when given a judgment requirement, first think about "what the answer looks like"—options, a scale, a probability, or coordinates on an image—then pick the question type
- The full ability to read answers: check the distribution with
probabilities, the certainty withconfidence, and readscoretogether withlegend - Turning "uncertain" into code branches: auto-execute at high confidence, flag for review at medium confidence, escalate to a human at low confidence
- An introduction to image judgment: Box positioning plus the Danger Zone switch, laying the groundwork for scenarios like scanned-document recognition and OCR verification
Once you have practiced these five ways of asking, you have covered the everyday use of Jev. Next, choose either of two paths: to build a complete system, go to Efficient Workflows to learn four official architecture patterns; to see real projects first, Scenario Walkthroughs has 15 complete cases—for example live chat filtering: one request per message with three questions, judging abuse, spoilers, and spam together.
Ready? Start Lesson One: State →