Skip to content

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.py still runs, TYPESAFE_API_KEY is 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 AskingWhat It AnswersWhat's in the Answer
Choice multiple-choicewhich one to pick from fixed optionschoice, probabilities (probability for each option), confidence
Score ratingwhich level it lands on in the ordered scale you definescore (can land between two levels, e.g. 0.67), legend, probabilities, confidence
Noul yes/nothe probability that this judgment is truenoul (0–1; no separate confidence)
Confidence confidencehow certain this answer isa single number in 0–1; included with Choice / Score / Box answers, not with Noul
Box image localizationwhere the target is in the imagebox (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 other or none of the above option)
  • 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:

LessonContentDuration
2.1 Statehow 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 limits8 minutes
2.2 Choice questionsGive all options in criteria, read the probabilities of each option, and add an other option when the list is incomplete10 minutes
2.3 Score questionsDefine an ordered scale, read the score that can land between two levels, and split complex judgments into multiple questions weighted and merged in code10 minutes
2.4 Noul yes/no questionsHow to read 0–1 probabilities, 0.7 / 0.3 starting thresholds, and how to choose between it and Score8 minutes
2.5 ConfidenceHow confidence is computed from a probability distribution, the three-tier usage (auto-execute / flag for review / escalate to human), and thresholds that scale with risk12 minutes
2.6 Box and imagesPut images into state and questions, Box returns four edge ratios, and Danger Zone request headers and Image support in the Python SDK10 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:

python
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 with confidence, and read score together with legend
  • 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 →

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.