Docs
OfficialJev Cookbooks
Cookbook: Hierarchical Classification
Classify documents through deep patent, retail product, biomedical, and source-code hierarchies using parallel beam search over Choice probabilities.
- Format
- Docs
- Reading time
- 2 min
- Published by
- TypeSafe AI
- Last verified
- Sep 2026
Highlights
- Beam search keeps K=3 paths scored by geometric mean product(p) ** (1/decisions), length-normalized so shallow and deep leaves compare fairly.
- On four labeled hierarchies, beam K=3 matched 4 of 4 expected leaves while greedy matched 2 of 4, recovering CPC patents and Shopify products.
- Every sibling set becomes one Choice question keyed c0, c1, ...; each beam path runs as parallel questions so extra exploration barely adds latency.
- Taxonomies: CPC 2026.05 patents, Shopify 2026-02 products, MeSH 2026 (a DAG expanded into tree paths), and a frozen CookSafe snapshot.
- Defaults are model jev-1.12, beam width 3, max depth 12, epsilon 1e-9, with RetryPolicy(max_retries=5, backoff_initial=1.0, backoff_max=20.0).
Quickstart
python
@json_cache
def choose(state: str, labels: tuple[str, ...]) -> dict[str, float]:
if len(labels) == 1:
return {labels[0]: 1.0}
question, keys = child_question(labels)
response = client.system_one(
state=state, questions={"child": question}, model=MODEL
)
probabilities = response.answers["child"].probabilities
return {label: probabilities[key] for key, label in keys.items()}Watch out
Greedy search cannot recover an early wrong turn, and for hierarchies deeper than about 10 levels the cookbook recommends exp(mean(log(probs))) over the product formula to avoid precision errors.
Questions about this entry
Short answers drawn from the linked project or page.
Because greedy cannot recover an early wrong turn. On four labeled hierarchies, beam K=3 matched 4 of 4 expected leaves while greedy matched 2 of 4, recovering CPC patents and Shopify products.
By the geometric mean product(p) ** (1/decisions), length-normalized so shallow and deep leaves compare fairly. Every sibling set becomes one Choice question keyed c0, c1, ...; for hierarchies deeper than about 10 levels the cookbook recommends exp(mean(log(probs))).
Four: CPC 2026.05 patents from the cooperative patent classification bulk XML, Shopify's 2026-02 product taxonomy categories, MeSH 2026 which is a DAG expanded into tree paths, and a frozen CookSafe snapshot. Each ships with its own document and expected leaf.
Model jev-1.12, beam width 3, max depth 12 and epsilon 1e-9, with a RetryPolicy of max_retries 5, backoff_initial 1.0 and backoff_max 20.0. The cookbook also records a separation metric, the top path's score over its nearest rival, which is useful for spotting ambiguity but is not used for pruning.
Because the full probability distribution over a node's children is what makes the search possible: it gives you the edge probabilities the path score is built from, rather than a single winning label. A single-option node short-circuits to certainty without a call.
Barely. Every path in the beam runs as parallel questions, so extra exploration adds little wall-clock time. The helpers also render each search traversal as a static SVG, so you can inspect where the beam went rather than reading logs.
Compute the path score as exp(mean(log(probs))) rather than product(edge_probabilities) ** (1/decisions). That avoids precision errors once a hierarchy runs past roughly ten layers, where repeatedly multiplying and taking a fractional power loses accuracy.
More Jev resources like this
A live chat filter that asks three questions per message — category, toxicity, and spoilers — then turns the answers into show, highlight, dim, hide, or blur in plain code. The 29-message example hides seven, blurs two, and highlights six.
Jev CookbooksDocs#official#cookbook#moderation
Official
Decide which of 450 candidate product pairs from two beer catalogues describe the same entity: one three-level Score per pair splits 40 merges, 50 curator reviews, and 360 non-matches.
Jev CookbooksDocs#official#cookbook#entity-matching
Official
Classify SEC annual reports into 75 industry groups with one Choice each, then read confidence to decide when to fall back to a broader division.
Jev CookbooksDocs#official#cookbook#classification
Official
A support-ticket cookbook that lets Jev decide which requests are worth remembering, then wraps each call so saved tickets ride along in the state. Six later messages route correctly with memory against two without.
Jev CookbooksDocs#official#cookbook#memory
Official
Reconstruct Markdown from unformatted text in two requests: 16 Noul line-pair questions stitch split sentences, then 62 questions classify each block's type and companions.
Jev CookbooksDocs#official#cookbook#formatting
Official
Screen every message going into and out of an LLM app: a Noul describes possible hazards, a Score rates severity, and code thresholds the probabilities.
Jev CookbooksDocs#official#cookbook#guardrails
Official
From the Jev guides
Original write-ups on what this entry is for.
From the Jev AI model community
Posts from builders shipping with Jev right now.