Value Extraction: Dates, Emails, Phone Numbers, Amounts
💡 One-sentence summary: Use Jev Information Extraction to build a field pipeline—dates are split into components and assembled by code; emails/phones/amounts first find candidates with regex, then Jev picks the right one, and values can only come from the original text.
To feed fields from a document into a database, what you want is not "a piece of text that looks like an answer." The official docs provide two cookbooks for this: Date extraction (date extraction) asks about the components of a date—which month, which day, whether the year is stated, whether it's an absolute date or a relative date like "next Thursday"—leaving all calendar math to code; Pre-parsed value extraction (pre-parsed value extraction) is regex finds candidates, Jev picks the right one, code copies verbatim. The division of labor is just one line: the model reads the text; math and normalization live in code.
Why does this pipeline deserve its own lesson? The official Pre-parsed doc says it plainly: TypeSafe only picks from candidates already found by regex, so it cannot invent a value, nor can it transpose digits. Official real test results: all six date examples correct (including a date never stated in the document, correctly judged as "no date to produce," 0.46 to human review); four addresses in the email, picking the correct recipient mailbox at 0.97; three phone numbers, picking the correct mobile and normalizing it to +14155550177; four invoice amounts, picking the correct total and discount, with credit / charge probabilities at 0.03 and 0.98. This lesson runs the whole thing in about 15 minutes—the email/phone/amount part, after downloading the official cache, reproduces all the official numbers with zero Keys (verified by real testing on this page; why the date part can't do this is explained in Step 1).
What You'll Be Able to Do After This Lesson
- Write
extract_date(document, role): give it a document and the question "when is the deadline to return the form," and get back adateplus confidence; fill in the year when none is stated, parse "next Thursday" into a concrete date, and report an error for dates that can't be assembled - Use the
find+pickduo to extract values: regex grabs email/phone/amount candidates, Jev picks the right one, and the answer is a verbatim copy of a candidate—no inventing, no transposed transcription - Normalize the picked values: emails to lowercase, phone numbers to E.164 international format, amounts to
Decimalwith a credit / charge label - Reproduce the official value-extraction numbers without spending a cent: replay the official
json_cache.jsoncache, rerun with zero requests
Why Jev, Instead of Letting an LLM Extract Directly?
"Have the LLM extract the date from the contract" is many people's first instinct—it runs, but every character is retyped by the model.
| Capability | Let the LLM Extract Directly | Jev Information Extraction |
|---|---|---|
| Source of values | ❌ The model regenerates everything, possibly inventing a value or typing 14 as 41 | ✅ The options are exactly the candidates found by regex; the answer is a verbatim copy of one of them or none—official wording: cannot invent, cannot transpose |
| Calendar math | ❌ Asking the model to compute "what date is next Thursday" or "does month 2 have a 30th" is unreliable | ✅ The model only reads components (August / 14 / no year stated); assembly, inference, and validation all happen in code |
| Values not stated in the document | ❌ Tends to produce a date anyway | ✅ Three escape hatches—mode=none, year=none, pick=none—the official stance: missing components must be reported, not guessed |
| Confidence | ❌ You have to ask "are you sure," and the answer is still unstable | ✅ Every component carries a confidence; the date takes the weakest of the components used, below 0.60 goes to human review |
| Answer shape | ❌ Free text or JSON; downstream parsing will fail | ✅ Typed answers + probability distributions, directly usable by code |
In one sentence: an LLM rewrites the document for you, while Jev only reads it for you—the numbers written down always come from the original text.
Your Current Pain Points
- "I have the LLM extract the invoice total, and it occasionally transcribes
$1,315.50as$1,351.50—off by one digit position, the downstream billing is all wrong, and I can't trace which step failed" - "The contract never states a delivery date, yet the model still makes one up for me; I have to write another validation layer just to catch its hallucinations"
- "For relative dates like 'return by next Friday,' letting the model do the calendar math gives a different answer every run"
When to use this technique
When you need to:
- Extract structured fields from contracts, emails, invoices, and forms—dates, emails, phone numbers, amounts—straight into a database or billing flow
- Values that must come verbatim from the document—no fabrication, no mis-transcription, and anything missing must be explicitly reported as missing
- Relative dates ("today", "next Thursday") resolved into concrete dates, with the resolution rules written in your code—change the rules without changing the problem
And you don't want to:
- Parse JSON spat out by an LLM and then write another layer of "did it make things up again" validation
- Make a generative model do calendar math
- Retune the prompt all over again for every new document
🎒 Prerequisites
- Completed Noul yes/no questions: the credit / charge determination for amounts relies on Noul, 0.5 = a fifty-fifty split
- Completed Choice questions: all seven date questions are Choice, so you need to be able to write
criteriaoption maps and readchoiceandconfidence - Recommended reading: Confidence: know how the 0.60 review threshold can be tuned by risk
- Got Installation and your first request running:
.venvis usable. The value extraction part runs even without a Key (step 1 provides the official cache); the date part needsTYPESAFE_API_KEY - A cup of water ☕—this lesson is a complete mini-project: one date function + three kinds of value scenarios, where the model only reads text and all math and normalization happen in code
Follow along
First, let's settle how to run it: create value_extraction.py and paste the code block of each step below into the same file in order. This lesson has two parts with two ways to run them:
- Steps 2–4 (dates): the official cache doesn't match the cache keys of the current code (detailed in step 1), so set
TYPESAFE_API_KEYand run live—six examples make 6 requests in total, answers are cached locally, and reruns don't cost again - Steps 5–6 (email/phone/amount): after downloading the official
json_cache.json, reproduce all the official numbers with zero Keys
No Key for now? Skip straight to step 5 and get value extraction running first; for the date part, read against the official recorded numbers on this page—every step is annotated.
Step 1: set up the environment, download the official caches, and prepare the two extraction example sets
Why: each of the two official examples ships with a recorded answer cache json_cache.json—the value extraction one verifiably replays verbatim with zero Keys; the date one's keys don't match the current code, so it can only run live. Get the materials ready first so every later step has answers to check against.
Install the dependencies (the install commands of the two official cookbooks merged; the typesafe-sdk version range explicitly pinned per cooksafe 0.2.0's dependency declaration typesafe-sdk<0.8.0,>=0.7.0; cooksafe is the official cookbook companion utility library, self-described on PyPI as "Shared helpers for the TypeSafe cookbooks"—this page uses its JsonCache cache):
pip install 'typesafe-sdk>=0.7.0,<0.8.0' ipython phonenumbers 'cooksafe>=0.2.0,<0.3.0'Download the official cache for value extraction (raw direct link, verified working):
curl -sL -o values_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/pre_parsed_value_extraction_cookbook/json_cache.jsonCreate value_extraction.py and paste in the file header—the client mounts two caches, one for dates and one for values, each used for its own part:
import os
import re
from datetime import date, timedelta
from decimal import Decimal
from pathlib import Path
import phonenumbers
from cooksafe import JsonCache
from typesafe_sdk import Choice, Noul, TypeSafeClient
# 官方录制版本:Date extraction 用 jev-1.12,
# Pre-parsed value extraction 用 jev-1.14.0。
# live 跑日期部分时换成你锁定的版本 ID;jev-latest 别名会随版本漂移。
DATE_MODEL = "jev-1.14.0"
VALUE_MODEL = "jev-1.14.0"
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"), # cached re-renders need no key
base_url=os.environ.get("TYPESAFE_BASE_URL"),
timeout=30.0,
)
# 日期:缓存你自己 live 跑的答案(官方那份对不上,见下方提示框)
date_cache = JsonCache(Path("date_cache.json"))
# 值:官方缓存,零 Key 重放第 5、6 步全部官方数字
values_cache = JsonCache(Path("values_cache.json"))
print("setup ok")Run python value_extraction.py.
You should see: setup ok—this step is just assembly; no requests have been sent yet.
⚠️ Why we don't download the official date cache
The official repository also publishes the cache for the date part, but my testing shows: replaying with this page's code (i.e., the current official documentation code) plus cooksafe 0.2.0, all six calls miss the cache—the cache keys don't match (most likely the recording script is out of sync with the current documentation code), so the SDK falls back to real requests, and without a Key that's 401. So use your own date_cache.json for the date part; the official numbers are reproduced on this page for you to check answers against. The official value extraction cache verifiably replays verbatim—use it with confidence.
setup okprinted, andvalues_cache.jsonis in the working directory
Step 2: the seven date questions—Jev information extraction reads components first, no math
Why: asking the model to directly answer "what's the due date" amounts to making it do calendar math. The official approach breaks each component of the date into small closed sets: twelve months, days 1–31, and a window of years—so each component becomes a Choice, all asked in parallel in one request (the mechanism for multiple questions in one request is covered in Parallel questions and speculative fan-out). The model reads the text; the code does the calendar.
First prepare the four official example documents, then paste in the definitions of the seven questions:
CONTRACT = "This agreement is effective January 1, 2025 and expires December 31, 2027."
FORM = "Please return the signed form by August 14."
SURVEY = "Heads up - the customer survey closes today at 5pm."
REVIEW = "Let's schedule the design review for next Thursday."
MONTHS = {
"January": 1, "February": 2, "March": 3, "April": 4,
"May": 5, "June": 6, "July": 7, "August": 8,
"September": 9, "October": 10, "November": 11, "December": 12,
}
WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
YEAR_WINDOW = list(range(1900, 2051)) # 1900..2050
def date_questions(role: str) -> dict[str, Choice]:
"""Seven typed choices that read a date's shape and parts off the text -- no math."""
absent = "The document does not state this, or it is not this kind of date."
return {
"mode": Choice(
instructions=(
f"How is {role} written? 'absolute' = a calendar date naming a month (e.g. "
"'August 14', 'the 3rd of March'); 'relative' = given relative to today (today, "
"tomorrow, the day after tomorrow, or a named weekday such as 'next Thursday'); "
"'none' = the document does not state this date."
),
criteria={"absolute": None, "relative": None, "none": None},
),
"month": Choice(
instructions=f"If {role} is an absolute calendar date, which month is it in?",
criteria={m: None for m in MONTHS} | {"none": absent},
),
"day": Choice(
instructions=f"If {role} is an absolute calendar date, which day of the month (1-31)?",
criteria={str(d): None for d in range(1, 32)} | {"none": absent},
),
"year": Choice(
instructions=(
f"If {role} is an absolute calendar date, which year? Pick 'none' if the document "
"states no year (code infers it), or 'out_of_range' if a year is stated but not "
"in the list."
),
criteria={str(y): None for y in YEAR_WINDOW}
| {
"out_of_range": "A year is stated for this date but is outside the listed range.",
"none": "No year is stated for this date.",
},
),
"day_anchor": Choice(
instructions=(
f"If {role} is relative to today, which day is it? 'today', 'tomorrow', "
"'day_after' (the day after tomorrow), or 'weekday' (a named day of the week)."
),
criteria={
"today": None, "tomorrow": None, "day_after": None,
"weekday": None, "none": absent,
},
),
"weekday": Choice(
instructions=f"If {role} names a day of the week, which one?",
criteria={w: None for w in WEEKDAYS} | {"none": absent},
),
"week_offset": Choice(
instructions=(
f"If {role} names a weekday, which week is it in? 'next' for 'next Thursday' or "
"'Thursday next week'; 'current' for 'this Thursday'; 'none' for a bare weekday "
"with no qualifier (just 'Thursday' / 'on Thursday')."
),
criteria={"current": None, "next": None, "none": absent},
),
}The division of labor among the seven questions—mode says how this date is written (absolute / relative / not written), while the other six read components: absolute dates need month + day + year, relative dates need day_anchor (today / tomorrow / the day after tomorrow / some weekday), and when a weekday is named, weekday and week_offset say which one and which week. The code only reads the questions that mode actually needs.
Note the two escape hatches for year: none = the text doesn't state a year, the code fills it in; out_of_range = it's stated but outside 1900–2050, report it rather than guess. The official material also offers an alternative for when the option list is too long—see Advanced tips.
Next, paste in the request-sending function and, while you're at it, run the contract effective-date case:
@date_cache
def read_parts(document: str, role: str) -> dict:
"""One TypeSafe call -> {part: {choice, confidence}} for the seven questions."""
answers = client.system_one(
state=document, questions=date_questions(role), model=DATE_MODEL
).answers
return {
part: {"choice": ans.choice, "confidence": ans.confidence}
for part, ans in answers.items()
}
parts = read_parts(CONTRACT, "the date the agreement takes effect")
for name, part in sorted(parts.items()):
print(f"{name:<12}{part['choice']:<11}(conf {part['confidence']:.2f})")Run python value_extraction.py. With a Key set, one real request is sent (jev-1.14.0), and the answer goes into date_cache.json.
You should see (official jev-1.12 recorded numbers; your live run should match on component choices, with small differences in confidence):
day 1 (conf 0.98)
day_anchor none (conf 0.89)
mode absolute (conf 1.00)
month January (conf 1.00)
week_offset none (conf 0.99)
weekday none (conf 0.86)
year 2025 (conf 0.97)Three ways to read this:
The model did no math: it only said "January", "1", "2025"—it never said which weekday that is or how far from today; that's the job of the code in step 3
Components that don't apply answer
none: an absolute date doesn't needday_anchor/weekday, allnonewith high confidenceEvery component carries its own confidence: this machine knows how solid each of its readings is; step 4 uses them to compute the confidence of the whole date
I can say what each of the seven questions reads, and
modedecides which ones the code reads
Step 3: the code assembles the date—calendar math stays out of the model
Why: with the components in hand, the rest is entirely deterministic work: unstated years are filled in from today, "next Thursday" is resolved per your declared conventions, and unsatisfiable combinations like February 30 raise an error. The official material writes this as a pure function—no requests sent, no logging, so it can be unit-tested on its own.
Paste in the assembly code:
TODAY = date(2026, 7, 30) # fixed reference "today" so relative dates resolve reproducibly
REVIEW_BELOW = 0.60 # gate: a date below this confidence is flagged for a human
def resolve_weekday(today: date, weekday: str, week_offset: str) -> date:
"""Which date a named weekday points to, by our stated convention: a bare weekday is the next
occurrence on or after today; 'next' is the following calendar week; 'current' is this week."""
w = WEEKDAYS.index(weekday)
this_monday = today - timedelta(days=today.weekday())
if week_offset == "next":
return this_monday + timedelta(days=7 + w)
if week_offset == "current":
return this_monday + timedelta(days=w)
return today + timedelta(days=(w - today.weekday()) % 7)
def assemble(parts: dict, today: date = TODAY) -> dict:
"""Resolve the parts TypeSafe read into a concrete date, in code. Confidence is the weakest of
the parts the shape actually used."""
mode = parts["mode"]["choice"]
confs = [parts["mode"]["confidence"]]
def result(resolved: date | None, note: str) -> dict:
usable = [c for c in confs if c is not None]
confidence = min(usable) if usable else None
needs_review = resolved is None or confidence is None or confidence < REVIEW_BELOW
return {
"date": resolved,
"confidence": confidence,
"needs_review": needs_review,
"note": note,
}
if mode == "none":
return result(None, "no such date stated")
if mode == "absolute":
month, day, year = (
parts["month"]["choice"],
parts["day"]["choice"],
parts["year"]["choice"],
)
confs += [
parts["month"]["confidence"],
parts["day"]["confidence"],
parts["year"]["confidence"],
]
if "none" in (month, day) or not day.isdigit() or month not in MONTHS:
return result(None, "absolute date incomplete")
if year == "out_of_range": # a year is stated but off the list -> flag, don't guess
return result(None, f"year outside {YEAR_WINDOW[0]}-{YEAR_WINDOW[-1]}")
if year == "none": # no year stated -> infer this year, bumped to next if well past
try:
resolved = date(today.year, MONTHS[month], int(day))
except ValueError: # e.g. February 30 -- an inconsistent read, not a real date
return result(None, f"impossible date: {month} {day}")
if resolved < today - timedelta(days=31):
resolved = date(today.year + 1, MONTHS[month], int(day))
return result(resolved, "")
try: # a stated, in-range year
return result(date(int(year), MONTHS[month], int(day)), "")
except ValueError:
return result(None, f"impossible date: {year}-{month}-{day}")
if mode == "relative":
anchor = parts["day_anchor"]["choice"]
confs.append(parts["day_anchor"]["confidence"])
if anchor == "today":
return result(today, "")
if anchor == "tomorrow":
return result(today + timedelta(days=1), "")
if anchor == "day_after":
return result(today + timedelta(days=2), "")
if anchor == "weekday":
weekday, offset = parts["weekday"]["choice"], parts["week_offset"]["choice"]
confs += [parts["weekday"]["confidence"], parts["week_offset"]["confidence"]]
if weekday not in WEEKDAYS:
return result(None, "relative weekday not read")
return result(resolve_weekday(today, weekday, offset), "")
return result(None, "relative day not read")
return result(None, f"unrecognized mode: {mode}")
def extract_date(document: str, role: str) -> dict:
return assemble(read_parts(document, role))
print(extract_date(CONTRACT, "the date the agreement takes effect"))Run it.
You should see (official recording: three parts used 1.00 / 0.98 / 0.97, take the weakest):
{'date': datetime.date(2025, 1, 1), 'confidence': 0.97, 'needs_review': False, 'note': ''}Read through the three pieces of logic; each has its own exit:
- The ambiguity of "next Thursday" is adjudicated by code: the officially declared convention — a bare weekday = the next occurrence starting today (inclusive);
next= the next calendar week;current= this week. You can change it to your own team's convention; what you change is the code, not the problem - If no year is written, infer it: first assemble it with this year; only jump to next year if it is already in the past by more than 31 days — a form dated 8/14 is this year when viewed on 7/30
- Dates that can't be assembled report impossible instead of being forced: a contradictory reading like February 30 directly returns
Noneplus a note, and step 4 sends it to a human
💡 This is the unique value of Jev
The confidence is the weakest of the parts used — an absolute date only looks at the four items mode + month + day + year; however day_anchor answers makes no difference. It's obvious at a glance which part is dragging things down, and whoever reviews it knows which half of the original sentence to check. An ordinary LLM can't give you this: it spits out a finished date in one shot, and you don't know which link was guessed.
- I can state the inference rules for
year=none(start from this year, only jump to next year if more than 31 days in the past), and the parsing convention for bare weekdays
Step 4: check answers against the six official examples; below 0.60 goes to a human
Why: whether an extraction setup can go live depends on how it behaves when "the document doesn't mention this date." The six official examples cover four ways of writing plus one trap: two dates with the year written in the contract, a form deadline without a year, a survey closing "today," a design review on "next Thursday," plus a kickoff call that the form never mentions at all (the form does contain a date, just not this one — specifically targeting the habit of "extracting any date you see").
Paste in the examples and the scoreboard:
# (document, question phrase, expected date) -- the expected value is only for the scorecard.
EXAMPLES = [
(CONTRACT, "the date the agreement takes effect", date(2025, 1, 1)),
(CONTRACT, "the date the agreement expires", date(2027, 12, 31)),
(FORM, "the deadline to return the form", date(2026, 8, 14)),
(FORM, "the date of the kickoff call", None),
(SURVEY, "the date the survey closes", date(2026, 7, 30)),
(REVIEW, "the date of the design review", date(2026, 8, 6)),
]
print(f"{'':3}{'question':<38}{'expected':<12}{'got':<12}{'conf':>6} flags")
print("-" * 84)
for document, role, expected in EXAMPLES:
r = extract_date(document, role)
got = r["date"].isoformat() if r["date"] else "none"
exp = expected.isoformat() if expected else "none"
mark = "OK" if r["date"] == expected else "XX"
conf = f"{r['confidence']:.2f}" if r["confidence"] is not None else " n/a"
flags = " <== review" if r["needs_review"] else ""
if r["note"]:
flags += f" ({r['note']})"
print(f"{mark:<3}{role:<38}{exp:<12}{got:<12}{conf:>6}{flags}")
print()
confident = [(doc, role) for doc, role, _ in EXAMPLES if not extract_date(doc, role)["needs_review"]]
review = [(doc, role) for doc, role, _ in EXAMPLES if extract_date(doc, role)["needs_review"]]
print(f"auto-accept ({len(confident)}):")
for _doc, role in confident:
print(f" - {role}")
print(f"\nsend to review ({len(review)}):")
for _doc, role in review:
r = extract_date(_doc, role)
print(f" - {role} (conf {r['confidence']:.2f} / {r['note'] or 'low confidence'})")Run. The six examples total 6 calls — the one from step 2 is already in the cache, so the first run sends 5 new requests; the later auto-accept / review sections make more calls to extract_date, all served from cache.
You should see (official jev-1.12 recording, TODAY = 2026-07-30, a Thursday; live numbers will differ slightly):
question expected got conf flags
------------------------------------------------------------------------------------
OK the date the agreement takes effect 2025-01-01 2025-01-01 0.97
OK the date the agreement expires 2027-12-31 2027-12-31 0.91
OK the deadline to return the form 2026-08-14 2026-08-14 0.95
OK the date of the kickoff call none none 0.46 <== review (absolute date incomplete)
OK the date the survey closes 2026-07-30 2026-07-30 0.94
OK the date of the design review 2026-08-06 2026-08-06 0.92
auto-accept (5):
- the date the agreement takes effect
- the date the agreement expires
- the deadline to return the form
- the date the survey closes
- the date of the design review
send to review (1):
- the date of the kickoff call (conf 0.46 / absolute date incomplete)Three things are worth stopping to look at:
- A date that wasn't written gets reported, not guessed: for the kickoff call row,
modeansweredabsolutebutmonthwasnone— the code rules "absolute date incomplete," with an empty date, confidence 0.46, needs_review. This is exactly the point of thenoneescape hatch in the official design for parts: missing parts get reported, not hallucinated - A form without a year fills it in itself: August 14 → 2026-08-14 (
TODAYis 2026-07-30, and August (month 8) hasn't passed yet, so no year jump needed) - Both "today" and "next Thursday" landed: survey closes → 2026-07-30 (same day); design review → 2026-08-06 (month 7, day 30 is a Thursday, "next" = day 4 of the next calendar week). The prerequisite for relative dates to be reproducible is that
TODAYis fixed — when you run it yourself, replaceTODAYwithdate.today(), or pin it down uniformly before running a batch
The go-live action is decided by a single needs_review field: False goes straight into the database, True goes to a human — for how to tune confidence thresholds by risk, see Confidence.
- The six-row scoreboard and auto-accept 5 / send to review 1 all match; I can point out why the kickoff call row should not be 2026-08-14
Step 5: email extraction — regex finds candidates, Jev picks the right one
Why: from this step on, it runs with zero keys. The hard part of emails isn't "finding all the addresses" — a regex can be written in an hour — butwhich of the four candidates is the one you want: which inbox the receipt goes to depends on whether you understood the sentence in the body saying "don't use the billing alias, send it to my personal inbox." This is exactly the official three-step method: regex finds candidates (over-capture is fine) → Jev picks the right one → code normalizes by copying verbatim.
Paste in the four helper functions and the email example:
NONE = "none" # the escape hatch on every selection: "none of the candidates fits"
EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
PHONE_RE = re.compile(r"\(?\+?\d[\d\s()\-.]{6,}\d")
MONEY_RE = re.compile(r"[$€£¥]\s?\d[\d,]*(?:\.\d{2})?")
def find(pattern: re.Pattern, text: str) -> list[str]:
"""Code-side candidate finder: recall-tuned regex, deduped, in document order."""
seen: set[str] = set()
out: list[str] = []
for match in pattern.findall(text):
span = match.strip()
if span and span not in seen:
seen.add(span)
out.append(span)
return out
@values_cache
def pick(document: str, candidates: list[str], question: str) -> dict:
"""TypeSafe selects which found span plays the role. Returns {choice, confidence}.
The options ARE the candidate spans, so ``choice`` is a verbatim copy of one of them (or the
``none`` hatch). The model chooses; code owns the string."""
criteria = {c: None for c in candidates} | {NONE: "None of these is the requested value."}
answer = client.system_one(
state=document,
questions={"pick": Choice(instructions=question, criteria=criteria)},
model=VALUE_MODEL,
).answers["pick"]
return {"choice": answer.choice, "confidence": answer.confidence}
@values_cache
def classify(document: str, question: str, options: list[str]) -> dict:
"""A small Choice over a fixed label set (currency, country, ...). Returns {choice, confidence}."""
answer = client.system_one(
state=document,
questions={"q": Choice(instructions=question, criteria={o: None for o in options})},
model=VALUE_MODEL,
).answers["q"]
return {"choice": answer.choice, "confidence": answer.confidence}
@values_cache
def is_true(document: str, question: str) -> float:
"""A yes/no Noul. Returns P(yes)."""
return (
client.system_one(
state=document,
questions={"q": Noul(instructions=question)},
model=VALUE_MODEL,
)
.answers["q"]
.noul
)
EMAIL_DOC = """From: Jane Doe <jane.doe@example.com>
To: billing@example.com
Cc: orders@example.com
Reply-To: jane.personal@example.net
Hi team - please don't use the billing alias for this one. Send my receipt to my
personal address instead. Thanks, Jane."""
emails = find(EMAIL_RE, EMAIL_DOC)
receipt = pick(EMAIL_DOC, emails, "Which email address does the sender want their receipt sent to?")
sender = pick(EMAIL_DOC, emails, "Which email address did this message come from (the From line)?")
print("candidates :", emails)
# code copies the picked value verbatim and normalizes (lowercase); it never re-types it
print(f"receipt -> : {receipt['choice'].lower():<28} (conf {receipt['confidence']:.2f})")
print(f"sender -> : {sender['choice'].lower():<28} (conf {sender['confidence']:.2f})")Run python value_extraction.py — everything hits the official cache, not a single request is sent.
You should see (official jev-1.14.0 recording; reproduced verbatim in this page's live test):
candidates : ['jane.doe@example.com', 'billing@example.com', 'orders@example.com', 'jane.personal@example.net']
receipt -> : jane.personal@example.net (conf 0.97)
sender -> : jane.doe@example.com (conf 1.00)Two design points:
- The options for
pickare the candidates themselves:criteriais the four address strings plus onenone, sochoicecan only be one of them,a verbatim copy — there's no way to invent a fifth address, and no way to transcribe it wrong, because there is no "retyping" step at all - If it can't pick one, it says so: when no candidate fits, the answer is
none, and the code treats it as "not found" rather than forcing a pick - Two questions, two requests, the same set of candidates: the recipient address is determined by the body (personal inbox wanted), the sender by the
Fromline — the judgment lives between the lines, which is exactly the part a regex can't do
💡 This is the unique value of Jev
The regex handlesrecall (grab everything possible; over-capture is fine), Jev handlesselection (read the body, pick the right one), and the code handlesfidelity (verbatim copy + lowercase normalization). Each of the three parts does its own job, and if one breaks it can be fixed in isolation — a direct LLM extraction stirs all three into a single generation, and when it's wrong you don't even know which part went wrong.
- Ran with zero keys and got receipt 0.97 / sender 1.00; I can explain why
pickcould never return an address not in the candidates
Step 6: phone numbers and amounts — normalize to E.164 and Decimal
Why: picking the right value is only the first half; it also has to take a form the system can use. The hard part with phones: three numbers look identical — which is a mobile, in which country —the digits themselves don't contain that information; the surrounding text does. The hard part with amounts: picking out the total isn't enough; you have to know whether it's a charge or a credit, otherwise Decimal can't even settle the sign.
Paste in the phone example:
PHONE_DOC = """Reach our San Francisco office at these numbers: main desk (415) 555-0199,
billing fax (415) 555-0142, and my direct cell (415) 555-0177. Call the cell if it's urgent."""
phones = find(PHONE_RE, PHONE_DOC)
mobile = pick(PHONE_DOC, phones, "Which of these is the direct mobile / cell number?")
region = classify(PHONE_DOC, "In what country is this office located?", ["US", "GB", "DE", "FR", "CA", "AU"])
# code copies the picked value and normalizes it with the model-supplied country
parsed = phonenumbers.parse(mobile["choice"], region["choice"])
e164 = phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)
print("candidates :", phones)
print(f"mobile -> : {mobile['choice']} (conf {mobile['confidence']:.2f})")
print(f"country -> : {region['choice']} (conf {region['confidence']:.2f})")
print(f"E.164 -> : {e164}")Then paste in the amount example:
MONEY_DOC = """Invoice INV-2087.
Subtotal: $1,200.00
Sales tax: $115.50
Total due: $1,315.50
A $50.00 courtesy credit from last month has already been applied."""
amounts = find(MONEY_RE, MONEY_DOC)
currency = classify(MONEY_DOC, "What currency are these amounts in?", ["USD", "EUR", "GBP", "JPY", "CAD"])
total = pick(MONEY_DOC, amounts, "Which amount is the total the customer must pay?")
credit = pick(MONEY_DOC, amounts, "Which amount is the courtesy credit that was applied?")
def to_decimal(value: str) -> Decimal:
"""Copy the picked value and parse the number in code (US grouping/decimal here)."""
return Decimal(re.sub(r"[^\d.]", "", value))
for label, chosen in [("total due", total), ("credit", credit)]:
is_credit = is_true(
MONEY_DOC,
f"Is the amount {chosen['choice']} a credit or refund to the customer, not a charge?",
)
kind = "credit" if is_credit > 0.5 else "charge"
print(
f"{label:<10}: {chosen['choice']:<10} -> {to_decimal(chosen['choice'])} {currency['choice']} "
f"({kind}, P(credit)={is_credit:.2f})"
)
print("\ncandidates :", amounts)Run it.
You should see (official jev-1.14.0 recording; reproduced verbatim in this page's live test):
candidates : ['(415) 555-0199', '(415) 555-0142', '(415) 555-0177']
mobile -> : (415) 555-0177 (conf 1.00)
country -> : US (conf 1.00)
E.164 -> : +14155550177
total due : $1,315.50 -> 1315.50 USD (charge, P(credit)=0.03)
credit : $50.00 -> 50.00 USD (credit, P(credit)=0.98)
candidates : ['$1,200.00', '$115.50', '$1,315.50', '$50.00']Look at the four parts one by one:
- Phone: Jev picks the number + reads the country,
phonenumbershandles formatting——(415) 555-0177contains not a single digit that says "this is a mobile" or "I'm in the US"; those two facts come from phrases like "my direct cell" and "San Francisco office". E.164 assembly is pure code, with the country passed in as a parameter - Amount: a single Noul question determines the sign——"is this amount a credit or a charge for the customer" yields 0.03 and 0.98 respectively, and the lopsided probabilities give
Decimal's sign a basis;0.5is the hard cutoff—anything close to 0.5 should go to human review (Noul has no confidence) classify's labels are the closed set you choose: countries[US, GB, DE, FR, CA, AU], currencies[USD, EUR, GBP, JPY, CAD]——to adapt to your business region, just change these two lists; if the official recommended list may not cover everything, add another/none of the aboveoption so the model has a way to say "none of these fit"pickcomes with confidence: in the official cache, the "total" pick question is recorded as 0.56 (not printed in the output, but recorded in the cache)—the answer was picked correctly, but with mediocre certainty. Whether low-confidence picks need review: write the rule into your code following theREVIEW_BELOWapproach from step 4
The officials note two limits at the bottom of the page; note them for now, expanded in Advanced Techniques:
A single Choice has at most 255 options; with more candidates, pick in two stages first
Finding candidates is the labor-intensive part——emails, phone numbers, and amounts are luckily covered; person names have no good regex, so candidates must come from a roster or NER
Ran E.164
+14155550177and P(credit) 0.03 / 0.98 with zero Key; I can explain who determines the phone number and the country respectively, and who assembles E.164
📋 Magic Prompts
The "Prompts" on this page are API question and code templates—copy them, replace the 【】 placeholders (those with ? are optional), and you can plug them into your own documents. Three pieces: the date-components question, the candidate-picking question, and the normalization pipeline.
📝 Seven Date-Component Questions (Choice edition)
Expected effect: any requirement to "ask for a date by role"—contract effective date, form deadline, rescheduled meeting date—works with the same set of questions by just swapping the role, and the answer is always components, never a finished date.
# 必填项:【日期角色】换成你要问的那个日期的自然语言描述
DATE_QUESTIONS = {
"mode": Choice(
instructions="【这个日期是怎么写的?absolute=点名月份的日历日期;relative=相对今天;none=文档没写】",
criteria={"absolute": None, "relative": None, "none": None},
),
"month": Choice(
instructions="【若是绝对日期,是几月?】",
criteria={【m: None for m in 十二个月】} | {"none": "文档没写或不是这种日期"},
),
"day": Choice(
instructions="【若是绝对日期,是几号(1-31)?】",
criteria={【str(d): None for d in range(1, 32)】} | {"none": "文档没写或不是这种日期"},
),
"year": Choice(
instructions="【若是绝对日期,是哪年?没写选 none,超出范围选 out_of_range】",
criteria={【str(y): None for y in 你的年份窗口】}
| {"out_of_range": "写了年份但在列表外", "none": "没写年份,代码来补"},
),
"day_anchor": Choice(
instructions="【若是相对日期,锚在哪天?today / tomorrow / day_after / weekday】",
criteria={"today": None, "tomorrow": None, "day_after": None, "weekday": None,
"none": "文档没写或不是这种日期"},
),
"weekday": Choice(
instructions="【若点名了星期几,是哪一个?】",
criteria={【w: None for w in 七个星期】} | {"none": "文档没写或不是这种日期"},
),
"week_offset": Choice(
instructions="【若点名星期几,是哪一周?next=下一日历周;current=本周;none=光秃秃没限定】",
criteria={"current": None, "next": None, "none": "文档没写或不是这种日期"},
),
}
# 选填项:窗口按你的业务改——1950–2035 或未来十年;列表太长见进阶技巧的预筛做法?
# 输出规范:每题 answer.choice + answer.confidence;代码只读 mode 用得上的部件
# 约束条件:
# ✅ 每道不适用的部件都给 none 出口——缺的部件要被报出来,不是被猜出来
# ✅ 日历数学(补年份、解析「下周四」、校验 2 月 30)全放代码
# ❌ 不要问「截止日期是几月几号」——那是让模型做数学+回答二合一✅ Candidate-Picking Question (pick edition)
Expected effect: any field where "a regex can find the candidates, but you need to read the context to know which one to pick"—recipient email, mobile number, invoice total, support agent ID—fits this one template.
from typesafe_sdk import Choice
# 必填项:candidates 传正则抓出的候选(去重、按文档序),问题问「角色」不问「形状」
picked = client.system_one(
state=【整份文档原文】,
questions={
"pick": Choice(
instructions="【哪个候选是……?例如:寄件人希望收据寄到的那个邮箱】",
criteria={c: None for c in 【candidates】}
| {"none": "None of these is the requested value."},
)
},
).answers["pick"]
# 选填项:同一批候选换一个 role 再问一次(发件人 vs 收件人)——两次请求、同一副选项?
# 输出规范:answer.choice 是某个候选的逐字拷贝或 "none";answer.confidence 可接复核线
# 约束条件:
# ✅ 选项就是候选字符串本身——答案是拷贝,不是重新生成
# ✅ 正则调召回不调精度:多抓的让 Jev 挑掉,漏抓的谁也救不回来
# ❌ 候选超过 255 个别硬塞——先分区块挑,再挑区块内的 span(见 C4)🔧 Normalization and Review (code edition)
Expected effect: the picked value becomes a form the system can use directly; every step is pure code, unit-testable, and free.
# 必填项:按字段类型选规范化器
normalized = {
"email": lambda v: v.lower(), # 逐字拷贝 + 小写
"phone": lambda v: phonenumbers.format_number( # 读国家 + E.164
phonenumbers.parse(v, region["choice"]),
phonenumbers.PhoneNumberFormat.E164),
"amount": lambda v: Decimal(re.sub(r"[^\d.]", "", v)), # $1,315.50 -> 1315.50
"date": assemble, # 部件 -> date,见第 3 步
}
# 选填项:credit/charge 用一道 Noul 定符号——P(credit) > 0.5 是 credit,贴着 0.5 转人工?
# 输出规范:值 + provenance(来自哪个候选/哪些部件)+ confidence + needs_review
# 约束条件:
# ✅ 规范化只处理「选中的那个字符串」,绝不重新生成
# ✅ 复核线(日期 0.60 起步)按风险调:进账单的金额从严,进统计报表的可松
# ❌ 别假设逗号一定是千分位——欧式格式 €1.315,50 正相反,先问一道 Noul「这份文档用逗号当小数点吗」再分支Checkpoint ✅
- Steps 5 and 6 reproduce all official numbers with zero Key: receipt 0.97 / sender 1.00 / E.164
+14155550177/ total P(credit)=0.03 / credit P(credit)=0.98 - I can explain what each of the seven date questions reads, and how
modedecides which components the code reads - I know that a date's confidence is the weakest of the components used; below 0.60 goes to a human; a date not stated in the document is reported as
none+ note, not made up - I can explain why
pickcannot possibly fabricate values or mis-transcribe digits: the options are the candidates themselves, and the answer is a verbatim copy - I know the two limits: Choice allows at most 255 options (if exceeded, pick in two stages); for values like person names that have no good regex, candidates must come from a roster, NER, or LLM proposals
Pitfall Warnings
❌ Making the LLM "retype" the value
Direct LLM extraction is essentially having it retype and output $1,315.50—transposing one digit ($1,351.50) or hallucinating a value not in the document both happen at this "regeneration" step. The official three-step method deletes this step entirely: regex finds candidates → Jev picks among the candidates → code copies verbatim and normalizes. The harshest line from the officials: TypeSafe only picks among candidates found by the regex, so it cannot invent a value and cannot mis-transcribe digits.
❌ Regex tuned too strict, the true value falls outside the candidates
pick's options are exactly the candidates you give it—anything not in the candidates, no matter how smart it is, it cannot pick. The officials define the first step's task as recall: when tuning the regex, better to over-capture (incidentally grabbing order numbers, fax numbers, subtotals is fine—Jev will pick them out) than to miss the true value. Over-capturing costs a few extra options in one request; missing costs this record being wrong forever.
❌ Expecting the date cache to replay with zero Key
The date json_cache.json published in the official repo doesn't match the cache keys of the current documentation code (tested on this page: all six calls missed, the SDK fell back to real requests, and without a Key it returned 401)—most likely the function signatures at recording time are out of sync with the current code. For the date part, set TYPESAFE_API_KEY and run with your own cache; when checking against official numbers, use the scoreboard transcribed on this page. The official cache for value extraction is unaffected—tested to replay verbatim.
❌ Calling to_decimal on any amount you see, and using it directly on any Chinese document
Both are easy traps. First: Decimal(re.sub(r"[^\d.]", "", value)) assumes "comma = thousands separator, dot = decimal point" — true for $1,315.50, exactly the opposite for €1.315,50; the official docs recommend first asking a Noul question "does this document use the comma as the decimal point" and branching on the answer. Second: the official docs state that Jev is trained mainly on English, and other languages (including Chinese) work but with lower accuracy — before putting Chinese contracts and invoices into production, run a batch on your own documents first to check the probability distribution; see Models and Pricing for language support details.
Advanced Techniques (optional)
Year list too long? Pre-filter first. year's 1900–2050 has 151 options, and the officials themselves say "if this annoys you, first extract the year-like numbers from the text and only give those to the model as options"—with a smaller candidate window, the question is also more focused. This is the same idea as step 5: candidate generation that can be delegated to code shouldn't bother the model.
More than 255 candidates: pick in two stages. The official approach: first pick a block (which paragraph / which table), then pick the span within the block—each stage's Choice stays within 255. The line-by-line search in Search and Matching demonstrates the first stage: label each line with an ID and have Choice point to the matching line.
Person names have no good regex. The officials say it plainly: finding candidates is the labor-intensive part—emails, phone numbers, and amounts have ready-made regexes, person names don't. Candidates can come from a roster you already have (HR system, customer list), or be proposed by NER / an LLM, with Jev doing the final pick.
Try the official examples for free. The bottom of the official cookbook page has a ready-made Playground share link—the pick question with the email body + four candidate addresses; open it (https://console.typesafe.ai/playground) and you can reword it in the browser and see the probability distribution. To generate your own link:
from cooksafe import make_playground_link
link = make_playground_link(EMAIL_DOC, {
"receipt": Choice(
instructions="Which email address does the sender want their receipt sent to?",
criteria={c: None for c in emails} | {"none": "None of these is the requested value."},
),
})
print(link) # 链接里带着完整 state 和问题,别放敏感数据Plug it into your own document pipeline. The questions stay fixed — only the state changes: replace EMAIL_DOC with the email body you parsed, MONEY_DOC with the OCR'd invoice text, and the seven date questions and three value questions are reused as-is. The cache keys are composed differently on the two sides, and keeping this straight saves a lot of debugging time: the key for the value part includes the document, the candidates, and the questions (all arguments of pick / classify / is_true) — changing the document, the regexes, or the questions causes a miss and triggers a real request; the key for the date part contains only the document and the role — changing the questions inside date_questions will not cause a miss (the questions live in the function body, and the cooksafe docs explicitly say that changing the function body does not invalidate the cache), so the old answers are served as-is; if you want a real run after changing the questions, delete date_cache.json. Once your extraction volume grows, look at cascade extraction: a cheap model does the rough work first, and Jev only does per-field verification.
Lesson summary
✅ Jev information extraction, with dates solved like this: seven Choice questions read out the shape and components in a single request, and all the calendar math (filling in the year, parsing "next Thursday", validating 2-30, i.e. February 30) happens in assemble(); confidence = the weakest of the components used, and anything below 0.60 goes to a human.
✅ Values = regex candidates + Jev selection + verbatim copying: find handles recall, pick handles selection (the options are the candidates; the answer can only be a verbatim copy from the source or none), and code handles normalization—no fabrication, no misaligned transcription.
✅ All three value types normalized end to end: emails lowercased with 0.97 / 1.00, phones in E.164 +14155550177 form (the country is read out by classify), amounts converted to Decimal and tagged with a credit/charge sign (Noul 0.03 / 0.98).
✅ Reproducing the official numbers with zero keys: the value-extraction part replays the official cache verbatim as tested; the date part's cache keys don't match in testing, so run it live with your own cache (6 requests), with the scoreboard based on the official recording.
Key configuration fields recap:
| Field | Value on this page | Notes |
|---|---|---|
DATE_MODEL / VALUE_MODEL | jev-1.14.0 | Official recording: dates jev-1.12, values jev-1.14.0; a live run locks in your own version ID—don't use the drifting jev-latest |
TODAY | date(2026, 7, 30) | Pinning "today" makes relative dates reproducible; when running it yourself, switch to date.today() or pin it down uniformly before a batch run |
REVIEW_BELOW | 0.60 | Date confidence review threshold; adjust the tier based on risk |
YEAR_WINDOW | 1900–2050 + none / out_of_range | Two escape hatches added to the year option window |
| Three regexes | EMAIL_RE / PHONE_RE / MONEY_RE | Recall first; candidates deduplicated and kept in document order |
| Choice option cap | 255 | When exceeded, first pick blocks then spans (see C4) |
| Requests per document | Dates: 1 request (seven questions in parallel); each value 1–3 requests (pick / classify / is_true) | Everything goes through the cache; only a changed document or changed questions cause a miss |
Related tutorials:
- Cascade extraction: a cheap model does the work, Jev verifies, an expensive model backstops—the industrialized version of this page's pipeline: how to skip the big model's per-field reasoning once the field count grows
- Search and matching: reranking, line-by-line search, entity alignment—a hands-on look at two-stage shrinking when candidates exceed 255, plus per-line semantic search over 218-line documents
- Confidence—the principle behind the 0.60 review threshold, and the three-tier usage of "high: auto-execute / medium: flag / low: hand off to a human"
Next lesson preview
With the fields extracted, the next question is what to do with text that has lost its formatting. Next lesson: Structure recovery: turning plain text back into Markdown.
You will learn:
- Two passes to restore format-stripped plain text into Markdown: the first pass runs one Noul per pair of adjacent lines, stitching back sentences cut by hard line breaks; the second pass runs one Choice per block, classifying it as heading / paragraph / list / quote / code / callout
- Why every character of the output comes from the input—the model only makes judgments, all rendering is done by code, and a model that rewrites text will change your words
- The same division of labor as this page: the model reads the text, the code does the work—except this time what's being restored is structure, not values