Recipe 02: Refund intent detection #2

Recipe 02 of 60 · Level 1 (Beginner) · Workflow & service operations · Noul

Use case

Judge whether a customer message explicitly requests a refund so Python can flag it for the appropriate workflow.

What to build

The folder recipes/02-refund-intent-detection/ with notebook.ipynb, README.md, and fixtures/, meeting the recipe contract. Start from python tools/new_recipe.py 02 and the template in recipes/_template/.

Build notes

• One proposition: the customer explicitly requests a refund. Write it as a statement.
• Fixtures must include near misses: a complaint with no request, a question about refund policy, a request for a replacement, a refund mentioned in passing.
• Python flags a message when the noul value clears a threshold and writes it to a simulated workflow queue.
• Explain that Noul returns a probability and has no separate confidence field.

Decision design

• Noul. Write each proposition as a statement that is true or false. One independent question per label or concern, sent together in one request. Noul has no confidence field, so each threshold is chosen from examples and evaluated.

Level 1 scope

One bounded judgment over a short prepared input with direct inspection of typed results.

Acceptance criteria

• recipes/02-refund-intent-detection/notebook.ipynb runs top to bottom offline, with no key and no network, and its outputs are committed
• Live mode is opt-in (JEV_COOKBOOK_LIVE=1 with TYPESAFE_API_KEY) and uses the same question definitions as the offline run
• Fixtures are synthetic, include the hard cases named in the build notes, carry gold labels, and pass the fixture validator
• Every response fixture records its provenance, and the notebook states which mode it ran in
• Evaluation: Precision and recall across a threshold sweep, with the chosen threshold justified from the examples.
• A reader with basic Python can follow it end to end; every new term is explained where it first appears
• At least three individual typed answers are displayed and discussed before any aggregate metric
• No statement about Jev's quality, latency, or cost appears without recorded live inference; in a synthetic run, metrics are labelled as pipeline checks
• recipes/02-refund-intent-detection/README.md says what the recipe teaches, how to run it, and what was and was not measured live
• The pull request changes only recipes/02-refund-intent-detection/ and CI is green

Dependencies

• Blocked by Foundation: CI executes every notebook offline and validates fixtures #69 (CI executes every notebook offline and validates fixtures)
• Tracked in Epic: Level 1 · Beginner recipes #75

Sources

Read these before writing the questions.

• S02 · TypeSafe AI: Primitives (Questions): Choice, Noul, Score, independent questions, and dependent follow-up calls.
• S03 · TypeSafe AI: Confidence: Distribution-derived confidence and task-specific thresholds informed by observed outcomes.
• S04 · TypeSafe AI: How to build with TypeSafe: Narrow semantic judgments integrated with workflows, deterministic logic, and side effects controlled by code.

Out of scope

• Changes to shared code, the catalog, or the root README. If the shared package is missing something, open a foundation issue and link it here.
• Real side effects of any kind. Actions are simulated.