Recipe 40: Hierarchical classification #40

Recipe 40 of 60 · Level 4 (Advanced) · Data quality & knowledge graphs · Choice

Use case

Route documents through a taxonomy in stages while Python carries competing branches forward when early judgments are uncertain.

What to build

The folder recipes/40-hierarchical-classification/ with notebook.ipynb, README.md, and fixtures/, meeting the recipe contract. Start from python tools/new_recipe.py 40 and the template in recipes/_template/.

Build notes

• Route documents through a taxonomy in stages.
• When an early judgment is uncertain, Python carries competing branches forward.
• Baselines: a greedy single path and a flat classifier over the leaves. Count requests for each.

Decision design

• Choice. Options are a fixed set supplied by Python, including the fallback outcome this use case names. Show the choice, the per-option probabilities, and the confidence for individual examples before aggregating.

Level 4 scope

Stateful workflows, provenance, adversarial cases, model calibration, or several integrated decision stages.

Acceptance criteria

• recipes/40-hierarchical-classification/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: Leaf accuracy and request count against both baselines.
• State, provenance, or policy rules are enforced in helpers.py and covered by tests that hold for any model answer
• Fixtures include adversarial, conflicting, or stateful cases, and the notebook walks through at least one
• 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/40-hierarchical-classification/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/40-hierarchical-classification/ 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)
• Builds on Recipe 05: Document classification #5 (Document classification), Recipe 38: Abstention and review queues #38 (Abstention and review queues). Merge those first and reuse their patterns; do not copy their fixtures.
• Tracked in Epic: Level 4 · Advanced recipes #78

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.
• S06 · TypeSafe AI: Cookbooks: Worked patterns for extraction, citation checking, skill selection, hierarchical classification, and feature discovery.

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.