Agents: read the raw Markdown of this page, or start at llms.txt.
Screen with a Noul first
TL;DR When the next step costs more than the first question (a bigger state code must fetch, an LLM call, or a person), ask one Noul over the input alone first. Above
0.7run the expensive step, below0.3take the cheap path, and give the band between its own outcome (the docs' example: a quick look by a person). If the later questions would use the same state, don't screen: ask everything at once (Speculative fan-out). New in the docs on 2026-11-07.
Problem
Not every input needs your expensive step. A shared inbox mixes customers waiting on an order with newsletters, receipts and thank-you notes; full triage means fetching the sender's account and order history first. Running that on every message wastes the fetch, the tokens and, if a person or an LLM is involved, their time.
Pattern
From raw/docs/patterns__noul-screen.md: "Ask one yes/no question first, and run the expensive step only when the answer is a clear yes. A clear no gets cheaper handling, and an answer it can't settle gets a rule of its own, so every input ends up handled."
When to screen first. Jev "reads the state once, so you pay for the state once". If later questions would use the same state, send them all in one request (Speculative fan-out). Screening is worth the extra request when the later step costs something the first question doesn't:
| The later step needs | Example from the docs |
|---|---|
| A bigger state | "the customer record, the full thread, or an attachment that code has to fetch first" |
| A slower model | "The next step is an LLM call." |
| A person | "someone to look at the item" |
Thresholds. "Above 0.7 counts as yes, and below 0.3 counts as no. Both are good starting points." The band between "means the message doesn't settle the question, so give it its own outcome instead of rounding it to yes or no" (same 0.7 / 0.3 guidance as raw/docs/confidence.md; Confidence vs probability).
Implementation
The docs' example triages a shared inbox. The screen sees "only the message, as it arrived".
Step 1: ask whether the sender expects a reply
One Noul, expects_reply. The docs: "Instead of saying 'not waiting', the false criterion lists the kinds of message with nothing to answer, including a note from a person that needs no reply." The exact instructions and criteria are behind the page's "Try it in the Playground" link and not in our capture; the wording below is ours, written to that description.
from typesafe_sdk import Noul, TypeSafeClient
EXPECTS_REPLY = Noul(
# Wording ours; the docs' question text is behind the Playground link.
instructions="Is the sender of `message` waiting for a reply?",
criteria={
"true": "The sender asks for something or is waiting to hear back",
"false": "Newsletters, receipts, notifications, or a note from a person that needs no reply",
},
)
client = TypeSafeClient(model="jev-1.14.0") # reads TYPESAFE_API_KEY
def screen(message_text):
return client.system_one(
state={"message": message_text},
questions={"expects_reply": EXPECTS_REPLY},
)
The documented answer for Tom's message, verbatim (jev-1.14.0): it "reports a problem but asks for nothing", so it is "neither a clear yes nor a clear no".
{
"model": "jev-1.14.0",
"answers": {
"expects_reply": {
"type": "noul",
"noul": 0.44
}
},
"usage": {
"input_tokens": 414,
"output_tokens": 21
}
}
Jev's answers for five messages (raw/docs/patterns__noul-screen.md, jev-1.14.0, 2026-11-07 capture):
| Message | expects_reply |
|---|---|
| "I ordered a standing desk two weeks ago and the tracking hasn't updated... I'm moving on the 30th and need it before then." | 0.98 |
| "Just so you know, the desk arrived with one of the cross-bar screws missing. I had a spare so it's built now." | 0.44 |
| "Thanks, the desk arrived yesterday and it's great." | 0.10 |
| "20% off every desk and chair until Sunday. Unsubscribe | View in browser" | 0.02 |
| "Your payment of $129.00 was successful... replies to this address are not monitored." | 0.02 |
Step 2: handle yes, no and unsure
Verbatim from the docs (screen.py):
YES_ABOVE = 0.7
NO_BELOW = 0.3
def handle(message_id, screen_response):
expects_reply = screen_response.answers["expects_reply"].noul
if expects_reply < NO_BELOW:
# Newsletters, receipts, notifications. Nothing to answer.
file_away(message_id)
elif expects_reply > YES_ABOVE:
# A person is waiting. Fetch what triage needs and run the full request.
customer = fetch_customer(message_id)
triage(message_id, customer)
else:
# Something to look at, but maybe nothing to answer. One glance settles it.
queue_for_quick_look(message_id)
Of the five messages, one goes to triage (the standing desk); the thank-you note and the two automated messages are filed away; the missing-screw note goes to a person for a quick look.
The same handler in TypeScript with @typesafe-ai/sdk 0.7.0 (Node.js 22+), adapted (not in the upstream docs); question wording ours as above.
import { noul, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient({ defaultModel: "jev-1.14.0" }); // reads TYPESAFE_API_KEY
const YES_ABOVE = 0.7;
const NO_BELOW = 0.3;
export async function handle(messageId: string, messageText: string) {
const { answers } = await client.systemOne({
state: { message: messageText },
questions: {
expects_reply: noul("Is the sender of `message` waiting for a reply?", {
true: "The sender asks for something or is waiting to hear back",
false: "Newsletters, receipts, notifications, or a note from a person that needs no reply",
}),
},
});
const expectsReply = answers.expects_reply.noul;
if (expectsReply < NO_BELOW) {
fileAway(messageId);
} else if (expectsReply > YES_ABOVE) {
const customer = await fetchCustomer(messageId);
await triage(messageId, customer);
} else {
queueForQuickLook(messageId);
}
}
Step 3: triage only the messages that need a reply
The triage request sends the customer record with the message and "asks questions that each check one thing: repeat_contact reads customer.previous_contacts, and urgency counts from message.received. A real triage stage would ask more questions than this." The question keys, the Choice options and the Score levels below come from the documented answer; the level texts are its legend, verbatim; instructions and the state shape beyond the two named fields are ours.
from typesafe_sdk import Choice, Noul, Score
TRIAGE = {
"request": Choice(
instructions="What is the sender of `message` asking for?", # ours
criteria={
"order_status": None,
"return_or_refund": None,
"product_question": None,
"complaint": None,
},
),
"urgency": Score(
instructions="How soon does the sender need an answer, counting from `message.received`?", # ours
criteria=[
"No deadline is mentioned",
"The sender wants an answer soon but gives no date",
"The sender names a date or event within a week",
],
),
"repeat_contact": Noul(
instructions="Has this customer contacted us about this before, per `customer.previous_contacts`?", # ours
),
}
def run_triage(message, customer):
# Called from the docs' triage(message_id, customer) once the record is fetched.
# message: {"text": ..., "received": ...}; customer: {..., "previous_contacts": [...]}
return client.system_one(
state={"message": message, "customer": customer},
questions=TRIAGE,
)
The documented triage answer (jev-1.14.0): request = order_status (probability 1.0, confidence 1.0); urgency score 1.99, confidence 0.98, probabilities 0.0 / 0.01 / 0.99; repeat_contact 0.99; usage 803 input and 84 output tokens. "The repeat_contact answer comes from the record: with no previous contacts on file, the same message got 0.05." Per the docs, Dana's urgent, repeated order-status request "could go to the front of the queue".
Token note (our arithmetic from the two documented usages): the screen used 414 input tokens, the triage request 803; only messages that pass the screen pay the second.
When it fails
- The later questions use the same state. Then the screen only adds a round trip; the docs say send them all in one request and ignore what doesn't apply (Speculative fan-out).
- Rounding the unsure band. A 0.44 is not a weak no. The docs give the band "its own outcome"; folding it into "no" files away messages someone should have read.
- A screen that needs the context it was meant to save. The screen must be a question "the message alone can settle". If it needs the customer record, screen on something else or skip the screen.
- A vague
falsecriterion. The docs' screen lists concrete kinds of no ("the kinds of message with nothing to answer") rather than "not waiting". See Writing instructions and criteria that Jev reads correctly. - Thresholds copied from the example.
0.7and0.3are starting points; move them by the cost of a wrong yes and a wrong no, and test on your own data (Testing and evaluating a Jev workflow).
Variants
From the docs' "Other ways to screen":
- Check a cheap step first. "Run the cheap step, ask a Noul whether its output is right, and send only the outputs that fail that check to the expensive model." See Cookbook: SDE cascade.
- Several screens. "A content pipeline might check first for 'written in English' and then for 'about our product'. Each check removes inputs before the next, more expensive step."
- Screen before a Choice or Score. The companion Noul page lists screening as one of its uses (Companion Noul).
- Screen many candidates, then decide once. Not one input but one Noul per catalog item, sent in parallel chunks, then a longer-description Noul round on the survivors and one Choice over a shortlist: Cookbook: Infinite cardinality choice (a TypeSafe cookbook, not a variant the pattern page names).
Related
- Speculative fan-out — the default when later questions share the state
- Companion Noul — a Noul beside a Choice, in the same request
- Noul (yes/no) questions — reading a Noul; the 0.7 / 0.3 starting thresholds
- Confidence vs probability — why a Noul is thresholded on its value
- Patterns overview — the six documented patterns
- Cookbook: SDE cascade — a cheap step checked before the expensive one
- Cookbook: Infinite cardinality choice — Noul screens over a whole catalog before one Choice
Sources
- raw/docs/patterns__noul-screen.md (https://docs.typesafe.ai/patterns/noul-screen) — new 2026-11-07
- raw/docs/patterns.md (https://docs.typesafe.ai/patterns)
- raw/docs/patterns__fan-out.md (https://docs.typesafe.ai/patterns/fan-out)
- raw/docs/confidence.md (https://docs.typesafe.ai/confidence) — Noul thresholds
- raw/docs/cookbooks__infinite_cardinality_choice.md (https://docs.typesafe.ai/cookbooks/infinite_cardinality_choice) — the Noul-shortlist-then-Choice cookbook