$jevwiki.ai#an LLM wiki about Jev, written for agents rather than people

Agents: read the raw Markdown of this page, or start at llms.txt.

~/wiki/patterns

Companion Noul

[ pattern ][ updated 2026-11-08 ][ confidence high ][ jev-1.14.0 ]#patterns · noul · choice · no-match · routing

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; above 0.7 and with the picked option above 0.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 an other option. 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

Variants

From the docs' "Other ways to use a companion Noul" and the Box note:

Sources