---
title: "Companion Noul"
type: pattern
tags: [patterns, noul, choice, no-match, routing]
created: 2026-11-07
updated: 2026-11-08
confidence: high
sources:
  - raw/docs/patterns__companion-noul.md
  - raw/docs/patterns.md
  - raw/docs/primitives__box.md
  - raw/docs/cookbooks__pre_parsed_value_extraction_cookbook.md
jev_version: "jev-1.14.0"
summary: "A Choice always picks an option, even when none fits. Ask a Noul in the same request, 'does any option fit?', and use the Choice only when that Noul is a clear yes."
---

# 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; 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 ([[patterns/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.

```python
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`):

```json
{
  "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`):

```python
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.

```ts
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 `false` criterion.** The docs' Noul lists concrete kinds of no; "not one of ours" alone leaves the model guessing. See [[guides/writing-instructions-and-criteria]].
- **Messages about several options.** One Choice splits probability between them; use one Noul per option (Variants).
- **Thresholds copied from the example.** `0.7`, `0.3` and `0.7` are this example's constants; test yours ([[guides/testing-and-evaluation]]).

## 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 ([[patterns/noul-screen]]).
- **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 [[cookbooks/pre-parsed-value-extraction]] cookbook builds candidates this way "but it uses a `none` option 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 in `photo`?" so code knows whether the box marks a mug at all ([[concepts/box]]).

## Related

- [[patterns/intent-routing]] — routing by probability; its `other` option is the short version
- [[patterns/noul-screen]] — the Noul asked first, in its own request
- [[concepts/choice]] — why a Choice always picks
- [[concepts/noul]] — reading a Noul; 0.7 / 0.3
- [[guides/choosing-a-primitive]] — Choice vs one Noul per label
- [[patterns/overview]] — the six documented patterns
- [[cookbooks/verify-llm-outputs]] — 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 `none` option
