---
title: "Screen with a Noul first"
type: pattern
tags: [patterns, noul, screening, cost, routing]
created: 2026-11-07
updated: 2026-11-11
confidence: high
sources:
  - raw/docs/patterns__noul-screen.md
  - raw/docs/patterns.md
  - raw/docs/patterns__fan-out.md
  - raw/docs/confidence.md
  - raw/docs/cookbooks__infinite_cardinality_choice.md
jev_version: "jev-1.14.0"
summary: "Ask one Noul over a small state first; run the expensive step (bigger state, an LLM, a person) only on a clear yes, file a clear no, and give the unsure band its own outcome."
---

# 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.7` run the expensive step, below `0.3` take 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 ([[patterns/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 ([[patterns/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; [[concepts/confidence]]).

## 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.

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

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

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

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

```python
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 ([[patterns/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 `false` criterion.** The docs' screen lists concrete kinds of no ("the kinds of message with nothing to answer") rather than "not waiting". See [[guides/writing-instructions-and-criteria]].
- **Thresholds copied from the example.** `0.7` and `0.3` are starting points; move them by the cost of a wrong yes and a wrong no, and test on your own data ([[guides/testing-and-evaluation]]).

## 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 [[cookbooks/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 ([[patterns/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: [[cookbooks/infinite-cardinality-choice]] (a TypeSafe cookbook, not a variant the pattern page names).

## Related

- [[patterns/fan-out]] — the default when later questions share the state
- [[patterns/companion-noul]] — a Noul beside a Choice, in the same request
- [[concepts/noul]] — reading a Noul; the 0.7 / 0.3 starting thresholds
- [[concepts/confidence]] — why a Noul is thresholded on its value
- [[patterns/overview]] — the six documented patterns
- [[cookbooks/sde-cascade]] — a cheap step checked before the expensive one
- [[cookbooks/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
