Agents: read the raw Markdown of this page, or start at llms.txt.
Companion Noul
TL;DR A Choice always picks an option, "possibly with a high probability", even when none applies. Add a Noul to the same request that asks whether any option fits. Below
0.3, ignore the Choice; above0.7and with the picked option above0.7, act on the Choice; otherwise a person decides with the Choice's pick as a hint. The docs say this "usually works better" than anotheroption. New in the docs on 2026-11-07.
Problem
From raw/docs/patterns__companion-noul.md: "A Choice question always picks an option, even when none of them applies. [...] The model is answering the question it was asked, so it picks whichever of the three options is closest."
In the docs' example a message about a desk lamp, from a shop that sells a desk, a chair and a monitor arm, gets desk_pro at 0.96 with confidence 0.94. "Nothing in that answer tells you the message isn't about your desk." Thresholding the Choice's probability does not catch this.
Pattern
"Add a second question to the same request: a Noul question that asks whether any of the options fits at all. Your code uses the answer to the Choice only when the Noul is a clear yes."
Both questions ride in one request over the same state, so this costs no extra round trip (Speculative fan-out).
Why an other option falls short
The docs: adding other: 'Something else' "looks like less work, and it used to be the usual advice. But other competes with the product options for probability. A message that is partly about a product and partly about something else splits its probability between other and that product, and neither number tells your code what to do." With a companion Noul, the Choice picks only among real options and a separate question "with concrete true and false criteria decides whether any product fits. In our tests, that usually works better." (TypeSafe's tests; no numbers published.)
Implementation
The docs' example routes support messages to three product teams; "Messages about anything else, such as a lamp from another shop or a note from a recruiter, go to a general inbox instead."
Ask which product, and whether any fits
"Both questions refer to the product list by its key in the state, products. Jev sees the Choice question's option names, so names such as desk_pro say what each product is. The false criterion on the Noul question lists what counts as a no: another product, a service, or something you don't sell." The question text and the product list are behind the page's "Try it in the Playground" link and not in our capture; the keys below come from the documented answer, the wording is ours.
from typesafe_sdk import Choice, Noul, TypeSafeClient
QUESTIONS = {
"product": Choice(
instructions="Which product in `products` is `message` about?", # ours
criteria={"desk_pro": None, "chair_lite": None, "monitor_arm": None},
),
"about_our_product": Noul(
instructions="Is `message` about one of the products in `products`?", # ours
criteria={
"true": "The message is about one of the listed products",
"false": "Another product, a service, or something we don't sell",
},
),
}
# Illustrative product list (ours; the docs' list is not in our capture).
PRODUCTS = [
{"key": "desk_pro", "name": "Standing desk"},
{"key": "chair_lite", "name": "Office chair"},
{"key": "monitor_arm", "name": "Monitor arm"},
]
with TypeSafeClient(model="jev-1.14.0") as client: # reads TYPESAFE_API_KEY
response = client.system_one(
state={"products": PRODUCTS, "message": "My desk lamp stopped working after two weeks..."},
questions=QUESTIONS,
)
The documented response for the desk-lamp message, verbatim (jev-1.14.0):
{
"model": "jev-1.14.0",
"answers": {
"product": {
"type": "choice",
"choice": "desk_pro",
"confidence": 0.94,
"probabilities": {
"desk_pro": 0.96,
"chair_lite": 0.01,
"monitor_arm": 0.03
}
},
"about_our_product": {
"type": "noul",
"noul": 0.02
}
},
"usage": {
"input_tokens": 549,
"output_tokens": 63
}
}
Jev's answers for four messages (raw/docs/patterns__companion-noul.md, jev-1.14.0, 2026-11-07 capture):
| Message | Choice | Top probability | Noul |
|---|---|---|---|
| "The motor on my standing desk has started making a grinding noise... the 140 cm one" | desk_pro |
1.00 | 0.98 |
| "The chair arrived but the monitor arm didn't. Can you check where the arm is?" | monitor_arm |
1.00 | 0.99 |
| "My desk lamp stopped working after two weeks..." | desk_pro |
0.96 | 0.02 |
| "I'm a recruiter working with several furniture retailers and wondered if your head of operations is open to a quick call" | desk_pro |
0.81 | 0.02 |
The recruiter note still gets desk_pro at 0.81, above the example's 0.7 product threshold; only the Noul stops it.
Trust the Choice only when a product fits
"Read the Noul first. On a clear no, ignore the Choice [...]. A clear yes says the message is about one of your products, but not which one, so also check the probability of the product the Choice picked." Verbatim from the docs (route.py):
YES = 0.7
NO = 0.3
PRODUCT_SURE = 0.7
def route(message_id, response):
about_ours = response.answers["about_our_product"].noul
product = response.answers["product"]
product_probability = product.probabilities[product.choice]
if about_ours < NO:
# Nothing fits. The Choice's answer is noise; don't read it.
send_to_general_inbox(message_id)
elif about_ours > YES and product_probability > PRODUCT_SURE:
# The Choice is answering a question that applies, and it clearly picked one product. Use it.
send_to_product_team(message_id, product.choice)
else:
# Unsettled, or about our products but not clearly which one:
# a person decides, with the Choice's top option as a hint.
send_to_general_agent(message_id, suggested_product=product.choice)
The same router in TypeScript with @typesafe-ai/sdk 0.7.0 (Node.js 22+), adapted (not in the upstream docs); question wording ours as above.
import { choice, noul, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient({ defaultModel: "jev-1.14.0" }); // reads TYPESAFE_API_KEY
const YES = 0.7;
const NO = 0.3;
const PRODUCT_SURE = 0.7;
export async function route(messageId: string, message: string, products: unknown[]) {
const { answers } = await client.systemOne({
state: { products, message },
questions: {
product: choice("Which product in `products` is `message` about?", {
desk_pro: null,
chair_lite: null,
monitor_arm: null,
}),
about_our_product: noul("Is `message` about one of the products in `products`?", {
true: "The message is about one of the listed products",
false: "Another product, a service, or something we don't sell",
}),
},
});
const aboutOurs = answers.about_our_product.noul;
const product = answers.product;
const productProbability = product.probabilities[product.choice];
if (aboutOurs < NO) {
sendToGeneralInbox(messageId); // nothing fits: ignore the Choice
} else if (aboutOurs > YES && productProbability > PRODUCT_SURE) {
sendToProductTeam(messageId, product.choice);
} else {
sendToGeneralAgent(messageId, { suggestedProduct: product.choice });
}
}
When it fails
- Reading the Choice before the Noul. The Choice is "noise" on a clear no; reading it first is the failure this pattern exists to stop.
- A yes is not a pick. A clear yes says some option fits, "but not which one"; still check
probabilities[choice]. - A loose
falsecriterion. The docs' Noul lists concrete kinds of no; "not one of ours" alone leaves the model guessing. See Writing instructions and criteria that Jev reads correctly. - Messages about several options. One Choice splits probability between them; use one Noul per option (Variants).
- Thresholds copied from the example.
0.7,0.3and0.7are this example's constants; test yours (Testing and evaluating a Jev workflow).
Variants
From the docs' "Other ways to use a companion Noul" and the Box note:
- One Noul question per option. "When a message can be about more than one product, a Choice has to split its probability between them. Ask one Noul question per product instead [...]. Then the case where nothing fits needs no extra question, because every Noul comes back low."
- As a screen. Ask the Noul first, in its own request, and run the expensive Choice or Score only on a clear yes (Screen with a Noul first).
- Candidates from code. Code pulls possible values out of the text, uses them as the Choice options, and the companion Noul asks whether the right value is among them. The Cookbook: Pre-parsed value extraction cookbook builds candidates this way "but it uses a
noneoption instead of a companion Noul." - Box.
box(experimental, header-gated) "always returns a location in an image". Pair it with a Noul such as "Is there a coffee mug inphoto?" so code knows whether the box marks a mug at all (Box questions (experimental)).
Related
- Routing by probability — routing by probability; its
otheroption is the short version - Screen with a Noul first — the Noul asked first, in its own request
- Choice questions — why a Choice always picks
- Noul (yes/no) questions — reading a Noul; 0.7 / 0.3
- Choosing between Choice, Score, Noul — Choice vs one Noul per label
- Patterns overview — the six documented patterns
- Cookbook: Verifying LLM answers against their source — a Noul (
declines) decides which of two other Nouls in the same request code reads
Sources
- raw/docs/patterns__companion-noul.md (https://docs.typesafe.ai/patterns/companion-noul) — new 2026-11-07
- raw/docs/patterns.md (https://docs.typesafe.ai/patterns)
- raw/docs/primitives__box.md (https://docs.typesafe.ai/primitives/box) — Box always returns a location
- raw/docs/cookbooks__pre_parsed_value_extraction_cookbook.md (https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook) — candidates from code with a
noneoption